Build or Change Components in a Themeable UI Component Library

## Find Which Files a Component Change Touches Act as a careful contributor to a reusable, themeable, accessible component library. Before editing, identify the requested behavior, the affected component or utility, and every directly related surface. Use the repository's actual structure, but expect a component change to span some of these areas: - Runtime components and composables. - Public types and exports. - Theme recipes, variants, and default values. - Unit, rendering, snapshot, and accessibility tests. - User documentation and examples. - A local playground or demonstration page. Do not assume that all areas must change. Trace the existing component and its nearest analogue, then list only the surfaces required by the request. Keep source and test conventions scoped to those directories; do not apply them blindly to documentation, examples, or tooling. Preserve existing public behavior unless the task explicitly changes it. Treat attribute forwarding, default resolution, accessibility semantics, right-to-left behavior, and documented APIs as contracts rather than implementation details. ## Read Only the Guides the Change Needs and Start From the Generator Read the repository-level contributor guidance first, then load only the task-relevant references. For example, use component-structure guidance for props, slots, events, and template patterns; theme guidance for slots and variants; test guidance for rendering, snapshots, and accessibility; and documentation guidance for examples and markup. Do not load every reference merely because it exists. Start from the affected file, inspect a recent comparable implementation, and open additional guidance only when the change reaches that concern. Use the project's declared package scripts and supported package manager. After dependency installation, run any required preparation or type-generation step before starting a playground, documentation site, or checks. Use the appropriate local environment for the change: the main application playground, an alternate framework playground, a focused reproduction environment, or the documentation site. Prefer the repository's approved generator when creating a component. Review generated files before editing, and request only the templates needed for the task. If no generator applies, reproduce the established file layout and naming conventions manually. ## Keep the Theme Default Order and Right-to-Left Layouts Working Follow the library's established code conventions consistently: - Keep type-only imports separate when the toolchain or style guide requires it. - Define runtime prop defaults through the standard helper and document public defaults in the type-facing API. - Add stable slot markers to rendered elements. On the root element, a caller-supplied marker must override the component fallback; inner elements retain their own markers. - When automatic attribute fallthrough is disabled, order or resolve root bindings so caller attributes are not silently overwritten. - Build reactive theme output through the standard computed mechanism rather than evaluating theme state once. - Resolve defaults through the complete precedence chain: explicit component input, nearest group or field context, library-level theme overrides, component defaults, then application configuration as defined by the project. - Pass raw inputs to context helpers when proxying them would change injection precedence. When a nearer context is absent, fall back to the resolved component value instead of dropping a theme-level default. - Forward primitive-library props and events through the project's proxy-aware adapter so resolved defaults are retained. Use semantic design tokens rather than raw palette values. Use logical spacing, position, border, radius, and text-alignment properties so layouts work in both left-to-right and right-to-left contexts. Add explicit direction-aware alternatives for transforms, cursors, gradients, or transitions when logical properties cannot express the behavior. Keep the implementation aligned with existing patterns. Do not introduce a competing default system, prop-forwarding path, or theme-resolution layer for one component. ## Build a Component From Theme to Tests and Docs With a Checklist Track a new component or substantial component feature with a checklist: 1. Scaffold or create the component in the standard runtime location. 2. Implement behavior, public props, slots, events, and accessibility semantics. 3. Add or update the theme recipe, including slots, variants, compound variants, and semantic tokens. 4. Export public types and register any component-default interface required by the theme system. 5. Add focused tests for behavior, props, slots, attribute forwarding, directionality, and accessibility as applicable. 6. Update user documentation with usage, examples, and API details. 7. Add or update a playground example that demonstrates the changed behavior. 8. Run linting, static type checks, and the relevant test suite. Use snapshots only where the project treats them as a useful contract, and review generated changes rather than accepting them automatically. Keep tests focused on externally meaningful behavior and known precedence rules. When documentation deploys before a package release, preserve the project's approved prerelease marker on affected headings or examples. The marker intentionally communicates that merged documentation may describe functionality shipping in the next release; do not remove or report it as inconsistent without checking the release policy. ## Run Lint and Tests, Then Open a Pull Request With the Real Results Review the final diff against the nearest established patterns and the original request. Verify: - Component structure, public types, and exports are consistent. - Theme code uses semantic tokens and preserves the full default-precedence chain. - Root attributes and slot markers respect caller overrides. - Logical properties or explicit direction variants cover right-to-left behavior. - Tests cover the changed props, slots, behavior, and accessibility requirements. - Documentation contains the necessary usage, examples, and API changes. - Intentional prerelease documentation markers remain intact. Run the repository's lint, type-check, and relevant test commands, and report their actual results. Do not claim that checks pass from inspection alone. Update documentation when the public behavior changes. Use the repository's required commit-message convention and pull-request template. Link the relevant work item, identify the change type, describe the behavior and verification, and complete only checklist items supported by evidence. Do not rewrite, rebase, force-push, or collapse a contributor's commit history solely for neatness. Multiple development commits may be acceptable when the repository performs a squash merge; follow the repository's actual merge policy and the user's authorization.