The name of the component, along with a high-level description.
- Relevant historical or background information
- Link to Interaction Design spec
- Link to Visual Design spec
- Link to relevant work items, related existing issues, etc.
State whether this component be part of Nimble or Spright and provide justification or considerations leading to that decision.
A list of use cases, features, or functionality which are not goals for the component.
A list of the key features unique to this component.
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?
Screenshots and/or links to existing, canonical, or exemplary implementations of the component.
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.
Include code snippets showing basic component use and any interesting configurations.
For each section below, consider adding an "Alternatives" sub-section to describe any design alternatives and discuss why they were rejected.
The key elements of the component's public API surface:
- Component Name
- Props/Attrs: to match native element APIs, prefer primitive types rather than complex configuration objects and expose fields as both properties on the TypeScript class and attributes on the HTML element
- Methods
- Events
- CSS Classes and CSS Custom Properties that affect the component
- How native CSS Properties (height, width, etc.) affect the component
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.
Outline the component 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
Describe the plan for custom element form integration or why it's not necessary.
Components that are intended to replace a native form element (input, textarea, select) should generally behave like their native counterpart. See "More capable form controls" on web.dev for an overview of requirements. Leverage patterns from FAST Form Associated Custom Elements.
Describe the plan for Angular support, including directives for attribute binding and ControlValueAccessor for form integration. Depending on the contributor's needs, implementing Angular integration may be deferred but the initial spec should still document what work will be needed.
Describe the plan for Blazor support, including form integration. See the nimble-blazor CONTRIBUTING.md for details. Depending on the contributor's needs, implementing Blazor integration may be deferred but the initial spec should still document what work will be needed.
Work with Visual Design to create Figma files and other design assets. Be sure to account for the various component states, including hover, active, etc. as well as validity, and appearance variants.
Work with Interaction Design to create Figma files and other design assets. Be sure to account for the various interactions from mouse, keyboard, and touch.
Important aspects of the planned implementation with careful consideration of web standards and integration.
Highlight any alternative implementations you considered in each section.
If you think a section doesn't apply or don't know what to write, please DO NOT delete it. Either mark it "N/A" or leave it blank and the Nimble team can help you fill it in.
Key component states, valid state transitions, and how interactions trigger a state transition.
Consider the accessibility of the component, including:
- Keyboard Navigation and Focus
- Form Input and Autofill
- Use with Assistive Technology. For example:
- All components should define a role and support labels / being labelled so that assistive technology can identify them
- The implications shadow dom might have on how roles and attributes are presented in the accessibility tree
- Components which delegate focus require all global ARIA attributes to be enumerated
- Components should either follow an existing ARIA Pattern or provide thorough research indicating why a new pattern is appropriate. Research should include sources like Open UI Community Group and other popular design systems.
- Behavior with browser configurations like "Prefers reduced motion"
- Support for standard link behaviors if the component is an anchor or contains an anchor. These behaviors are enumerated in the anchor-patterns story. The story should be updated to include the new component.
Consider how the component will behave on mobile devices, including:
- Overflow behavior when screen space is constrained
- Interactions that are affected by touch rather than a pointer device (e.g. hover)
- Integration with common mobile experiences like native pickers, on-screen keyboards, and dictation
Consider whether the component has any special globalization needs such as:
- Special RTL handling
- Swapping of internal icons/visuals
- Localization
Are there any security implications surrounding the component?
Are there any performance pitfalls or challenges with implementing the component?
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?
What is the plan for testing the component, if different from the normal path? Note that the normal plan includes unit tests for basic state/behavior as well as end-to-end tests to validate the specific user stories described above.
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?
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?
Highlight any open questions for discussion during the spec PR. Before the spec is approved these should typically be resolved with the answers being incorporated in the spec document.