Contribution and Testing
Change the shared system with traceable specifications, working examples and evidence appropriate to the affected behavior.
Choose the right layer
| Change | Location | Review boundary |
|---|---|---|
| Shared component behavior | packages/ui/src/components/ | DOM semantics, API, keyboard, states and existing consumers |
| Shared tokens | packages/ui/src/tokens/tokens.css | Both themes, state pairs and generated catalogue |
| Foundation guidance | apps/styleguide/content/foundations.tsx | Decisions, specifications, examples, failures and verification |
| Developer guidance | apps/styleguide/content/developer-guides.tsx | Commands and code match the real workspace |
| Checked developer example | apps/styleguide/examples/ | Compiled source is also the displayed snippet |
| Topic navigation | apps/styleguide/content/navigation.ts | Discoverability, active route and complete link crawl |
Component contribution contract
- Define the problem, intended users and when the component should be used instead of a related component.
- Document anatomy, dimensions/token dependencies, variants, default/hover/focus/pressed/disabled and any selected/error/loading states.
- Specify keyboard behavior, accessible names, announcements, controlled/uncontrolled state and focus restoration.
- Include a minimal complete example and a realistic task example with recovery. Do not make every interaction a decorative no-op.
- Compare the documented API with the exported source and installed primitive types. State version and platform limitations.
Source-linked documentation
Developer examples are actual .tsx files included in the styleguide’s TypeScript build. The generator copies those source bytes into examples.json, so the CodeBlock shows the implementation exercised by the live demo. Keep snippets current with the generator; do not hand-edit the JSON.
pnpm --filter styleguide examples:generate
pnpm --filter styleguide examples:check
pnpm --filter styleguide tokens:generate
pnpm --filter styleguide tokens:checkRequired local checks
Run checks appropriate to the changed library behavior as well as the documentation app. The styleguide’s lint scope does not certify every package or the whole monorepo. Preserve unrelated worktrees and active jobs on this shared box.
pnpm --filter styleguide lint
pnpm --filter styleguide typecheck
pnpm --filter styleguide examples:check
pnpm --filter styleguide tokens:check
pnpm --filter styleguide build
# Start the built server, then:
pnpm --filter styleguide test:browserInteraction verification matrix
| Dimension | Inspect |
|---|---|
| Pointer/touch | Actual activation, adjacent targets, scrolling and cancellation |
| Keyboard | Tab order, Enter/Space/arrows where applicable, Escape and focus return |
| Assistive technology | Role, accessible name, state and announced changes |
| Layout | 320px reflow, long text, zoom and user text spacing |
| Appearance | Light/dark, forced colors, meaningful boundaries and focus contrast |
| Preferences | Reduced motion and saved/system theme behavior |
| Failure | Invalid input, failed request, denied clipboard/storage and recoverable state |
| Real task outcome | Persisted or returned result where the task requires it |
Evidence and claim boundaries
- A build proves compilation; a route crawl proves reachability; a lab test proves the exercised states. None alone proves a complete accessible design system.
- Keep command results, relevant screenshots and failure details with the release evidence. Inspect screenshots rather than merely generating them.
- Automated accessibility checks are useful but do not replace manual screen-reader and keyboard verification.
- For source, review and consent patterns, preserve provenance and qualified-review boundaries. Never invent language data to make a demo attractive.
Release and runtime verification
Build before restarting the preview. A production server serves its existing build, so edits are not live until the build and restart succeed. Confirm the expected route content and version, not just an active service. On this box, use bounded CPU/memory for builds and preserve other tenants.
The stable local preview is a task-owned user service, not a public deployment. Publishing to the live domain requires verifying the actual release/runtime boundary. Keep the canonical dirty checkout separate from this worktree.
Review checklist
- Can a new contributor run the documented commands and reproduce the example?
- Does every visible control have a meaningful result or an explicit local-simulation label?
- Do the docs distinguish implemented behavior from pending support or migration limitations?
- Does the complete route/link crawl include newly added topics and section anchors?
- Has the completion contract been updated with exact verified scope and remaining work?