Build and Update a UI Component Library That Follows the Design Rules

## Read the Right Spec for Each Task and Follow the Code When Docs Disagree Classify the task before editing and read the source that governs it. - For component behavior or APIs, read the public API guide, the implementation, and a nearby approved component. - For styling, read the detailed style specification, compile-time token file, runtime theme file, and adjacent scoped styles. - For build changes, read the build configuration and every custom plugin contract before changing the pipeline. - For tests, read the dedicated test configuration and nearby tests; for documentation, read the synchronization matrix. - Resolve conflicts in this order: source and active configuration, repository rules, specialized documentation, then general experience. - When source and documentation differ, follow the source and repair the stale documentation within the same approved scope. - Treat quick-reference tables as pointers to authoritative sections, not as independent copies of the rules. - Never invent an API or rely on memory for version-sensitive behavior; verify the installed version and its shipped documentation. Before implementation, list the affected exports, styles, tests, demo registries, documents, and build invariants. ## Give Each Component Its Own Folder With Code, Styles, and Tests Give each component one owned folder containing its implementation, scoped style file, export entry, and co-located unit test. Add public value and type exports separately, and register any required demo surface. - Use typed function components, define defaults in parameter destructuring, and set a stable display name. - Extend the appropriate native element attributes and omit only conflicting fields. - Keep component and type names in the repository's canonical case, style files in the configured filename form, and scoped class names in the configured class convention. - Preserve strict null checking and isolated-module rules; avoid untyped escape hatches and use explicit type-only exports. - Keep imports at the top, use configured project aliases, and do not place global selectors in component-scoped styles. - Compose classes through the scoped style map or approved class helper instead of hard-coding generated class names. - Keep reusable helpers focused and place them where the repository convention expects them. Do not change a component's public surface without updating its exports, tests, examples, and API documentation together. ## Use Shared Design Values for Colors and Corners Instead of Raw Numbers Maintain separate token layers for separate jobs: compile-time variables support calculations and mixins, while runtime CSS custom properties let consumers override themes. Do not treat the two layers as interchangeable. - Keep CSS-module naming and token injection consistent between build and test configurations. - Prefer runtime semantic tokens in component styles; use compile-time variables only where preprocessing is required. - Express color, focus, radius, elevation, typography, weight, and motion through the system's semantic roles rather than isolated raw values. - Avoid pure extremes and generic cold defaults when the design language defines tinted surfaces, warm text, or branded focus states. - Preserve intentional component silhouettes, state treatments, and shadow rules instead of flattening them into one generic pattern. - Keep global fonts, theme variables, and resets behind one global style entry. - Respect reduced-motion preferences and preserve visible focus, keyboard use, readable contrast, and documented accessibility roles. Take exact values and component-specific exceptions from the authoritative design specification and current source, never from memory. ## Test Each Component's Keyboard Use and Accessibility Use the repository's dedicated test configuration with its declared DOM environment, setup files, matchers, aliases, and CSS-module processing. Do not move test settings into a build configuration that the active test runner ignores. - Co-locate component tests and use the approved rendering, query, and user-interaction utilities. - Cover rendering, prop-driven classes, callbacks, disabled behavior, state changes, and relevant accessibility roles. - Exercise keyboard behavior with the keys required by the component pattern, including focus movement, activation, dismissal, and directional control. - Assert scoped classes through the imported style map rather than generated string literals. - Test imperative APIs by invoking them inside the test framework's state boundary and waiting for their mounted result; do not render a non-component API as JSX. - Keep shared test utilities centralized and use realistic user interactions instead of lower-level event shortcuts. - Meet the configured coverage thresholds and document any intentional exclusions instead of padding coverage with low-value cases. Run a focused failing test first for a defect, then the affected suite, and finally the complete required suite before completion. ## Keep the Build Modular So Apps Load Only the Components They Use Treat custom build plugins, package exports, and asset rules as consumer contracts. - Preserve separate ES-module and CommonJS outputs with module boundaries intact so unused components remain tree-shakeable. - Keep framework and approved helper packages external when they are peer dependencies; do not add runtime dependencies without an explicit requirement. - Preserve CSS code splitting and the mechanism that attaches each component's styles to its JavaScript entry. - Keep the global stylesheet entry complete while preventing unused component assets from entering consumer bundles. - Follow the repository's asset-copying and inlining policy, including font-format and public-path requirements. - Keep package export maps, published files, and side-effect declarations aligned with the generated structure. - Change build logic only after reading the custom plugin contracts and verify both component-level imports and the global style entry afterward. Generated distribution, demo-build, and coverage directories are outputs, not authoring surfaces, and must not be committed unless repository policy explicitly says otherwise. ## Update the Docs and Demo Pages Whenever a Component Changes Update every authoritative surface affected by a component change. - API or prop changes update the API manual from source; style changes update the detailed style specification. - Visual-language changes update the design brief, and new components update the user-facing prompt or catalog specification. - Component-count or coverage changes update every mirrored readme through the approved generator. - Demo registration may be split across route metadata, a renderer map, and a home-page catalog; update every independent registry. - Keep machine-readable counts derived from authoritative metadata rather than manually duplicating them. - Run the documentation synchronization checker and understand which demo or generated surfaces it does not inspect. - Regenerate tracked artifacts through the approved command instead of editing generated output directly. After registration changes, verify that selecting the demo route renders the intended page; a highlighted menu with an empty main area usually indicates a missing registry entry. ## Avoid Known Mistakes Like Bulk Replacements and Blank Demo Pages Use narrow, verifiable operations for changes that can silently corrupt many files. - For scripted replacements, verify every target immediately, account for immutable string operations, and avoid patterns that fail across quoted markup. - When a test tool writes structured output, provide its required output path instead of assuming a default file. - For DOM-to-image capture, embed the required font declarations in the capture root when the rendering engine cannot read the document font registry. - Do not refactor intentional internal component dependencies merely to improve a superficial tree-shaking metric. - Optimize package size by preserving on-demand imports and preventing unused large assets, fonts, and components from entering consumer bundles. - Diagnose blank demo pages by checking every independent page registry before changing the component implementation. Convert each confirmed recurring failure into a focused automated check when the repository provides a stable place for it. ## Pass All CI Checks Before Handing Over the Change Run the documented formatter check, lint, unit tests, and library build in the repository's required order. Run the full CI command before proposing a contribution. Confirm that: - all changed components, exports, tests, documentation, and demo registries are synchronized; - coverage or component-count badges were regenerated when their inputs changed; - no unapproved runtime dependency or generated output entered the change; - modular-output, CSS-splitting, and asset-loading contracts still hold; - the visual change matches the current token and component specifications; - the final diff contains only intended source and documentation changes. If any required check fails, repair the failure and rerun the relevant gate before presenting the diff. Use the repository's contribution format, and run release or publication workflows only when the task explicitly includes them. Report the exact checks run and any broader checks intentionally left out of scope.