3.6 KiB
Spec Title
Overview
The name of the component, along with a high-level description.
Background
Relevant historical or background information, related existing issues, etc.
Use Cases
Primary use cases for this component.
Non-goals
A list of use cases, features, or functionality which are not goals for the component
Features
A list of the key features unique to this component.
Risks and Challenges
Notable risks or challenges associated with implementing the component. Would we need to make any breaking changes in order to achieve this component's goals?
Prior Art/Examples
Screenshots and/or links to existing, canonical, or exemplary implementations of the component.
Design
Describe the design of the component, thinking through several perspectives:
- A customer using the component on a web page.
- A developer building an app with the component and interacting through HTML/CSS/JavaScript.
- A designer customizing the component.
API
The key elements of the component's public API surface:
- Component Name
- Props/Attrs
- Methods
- Events
Consider high and low-level APIs. Attempt to design a powerful and extensible low-level API with a high-level API for developer/designer ergonomics and simplicity.
Anatomy and Appearance
Screenshots and/or description of the basic appearance of the component. Outline its structure with a diagram of its visual tree (shadow dom). Enumerate key areas of visual customization, such as:
- Slot Names
- Host Classes
- Slotted Content/Slotted Classes
- CSS Parts
Implementation
Important aspects of the planned implementation with careful consideration of web standards and integration.
States
Key component states, valid state transitions, and how interactions trigger a state transition.
Accessibility
Consider the accessibility of the component, including:
- Keyboard Navigation and Focus
- Form Input
- Use with Assistive Technology
- e.g. The implications shadow dom might have on how roles are presented to the AT.
Globalization
Consider whether the component has any special globalization needs such as:
- Special RTL handling
- Swapping of internal icons/visuals
- Localization
Security
Are there any security implications surrounding the component?
Performance
Are there any performance pitfalls or challenges with implementing the component?
Dependencies
Will implementing the component require taking on any dependencies?
- 3rd party libraries
- Upcoming standards we need to polyfill
- Dependencies on other fast components or utilities
Do any of these dependencies bring along an associated timeline?
Test Plan
What is the plan for testing the component, if different from the normal path?
Tooling
Are there any special considerations for tooling? Will tooling changes need to be made? Is there a special way to light up this component in our tooling that would be compelling for developers/designers?
Documentation
What additions or changes are needed for user documentation and demos? Are there any architectural/engineering docs we should create as well, perhaps due to some interesting technical challenge or design decisions related to this component?
Resources
Any related resource links such as web standards, discussion threads, diagrams, etc.
Next Steps
What next steps, if any, are there? Is there some functionality that would be a nice-to-have or a common feature in other implementations that could be added but is not considered part of the MVP?