# Viewership UI: component conventions The contract every component (and every agent porting one) follows. If it conflicts with an upstream source, this file wins. ## 1. What a component is One folder per component under `src/ui/registry//`: | File | Purpose | | --- | --- | | `.astro` | The component. Consumers copy this. | | `*.ts` (optional) | Helpers the component imports. List them in `meta.files`. | | `demo.astro` | Gallery demo. Receives `variant` when `meta.variants` is set. | | `meta.ts` | `export default { ... } satisfies ComponentMeta` (see `src/lib/types.ts`). | The site finds components by globbing `meta.ts`. **Never edit a shared file to register a component.** `src/ui/registry/button/` is the reference; read it first. ## 2. Stack rules - **Astro + TypeScript + scoped CSS only.** No React, Tailwind or CSS-in-JS. - **No runtime npm dependencies** unless reimplementing is unreasonable. If you add one, check its license (MIT/ISC/Apache-2.0 only), list it in `meta.npm`, and say so in your report. - **Icons are inline SVG.** Use Lucide (ISC) paths. Iconoir (MIT) is fine when porting a component that used it. **Never copy Central Icons (proprietary).** - Import other registry components relatively (`import Button from "../button/Button.astro";`) and list their slugs in `meta.dependencies`. ## 3. Styling - Read every color, radius, shadow, font and easing from the `--vs-*` tokens in `src/ui/styles/foundation.css`. Never hard-code a theme color (pure `white` text on a filled accent is fine). - The root element gets class `vs-`. Scope everything under the component's `