Foundations

An agent generating NAMCHE UI code must follow these. They are read off the design system's own components, not invented, and the generated foundations page and agent contract carry the same rules.

• [reuse] Reuse first. Search the registry and component docs before making a UI primitive. Compose existing components; keep application-specific variants local.
• [boundaries] Keep the core independent. Routing, fetching, authentication, OpenAPI clients and backend concerns belong in the application, never the UI registry.
• [accessibility] Preserve accessibility. Give controls accessible names, bind labels and errors to inputs, name dialogs, preserve keyboard interaction and focus restoration, and announce async status without relying on colour alone.
• [tokens] Tokens only. Every colour, spacing, radius, motion and type value comes from @namche/design-tokens through the semantic Tailwind variables (bg-primary, text-foreground, rounded-card, …) or, for chart/illustration work only, the OKEANOS/HELIOS bridge utilities (text-okeanos-artemis, bg-helios-eos, var(--chart-1)…var(--chart-5)). Never hardcode a hex value or invent a colour.
• [composition] Composition uses the render prop, not asChild. Base UI components take render={<Button variant="outline">Open</Button>}, not the Radix asChild pattern. Check each component's actual props before writing a trigger.
• [typography] Namche Shadow only, at weight 500. Headlines take the font-display utility (700 for emphasis), running text is Namche Shadow Sans too (font-sans, weight 500, never Regular), no Geist. Buttons and meta labels are Namche Shadow Mono, uppercase.
• [primary] The primary action is an ink pill, not a brand colour. The default Button variant paints --gaia-erebos (near-black) with --gaia-selene (paper) text and an uppercase mono label. Every variant — including quiet ones like outline and ghost — names its own text colour explicitly, because the design tokens style bare <a> elements with an underline and ink colour; a variant that only inherits loses its label when rendered as a link through render.
• [lines] Lines differ by weight, never by grey. Use the 0.5px hairline (--hairline), the 1px stroke (--stroke) and the 2px bold stroke (--stroke-bold). Controls and cards sit at --radius-card (16), buttons are full pills.
• [text] One text tone. Running text is full ink, never muted or grey. Hierarchy comes from size, weight and structure. Semantic text tokens follow the token bridge; do not add opacity to create secondary text tones. Disabled states may retain opacity because they communicate a state.
• [mark] The mark is never a bullet or decoration. It appears at most once per surface, as identity.
• [elevation] No elevation, ever. The system defines no box-shadow.
• [day] Day and Night, switched by the theme, never by a component. The tokens on :root from @namche/design-tokens ARE the framework-neutral theming contract. Night is the dark class or data-mode="night" on <html>; the shadcn bridge then re-points every semantic variable. Default to the reader's system setting and let them pick (Auto, Day, Night), as the brand site does. Components never style a mode themselves: no dark: utilities and no night- tokens in a component, only semantic variables.
• [editorial] OKEANOS and HELIOS are only for charts and illustration. Never use them for product chrome.

Continue with Tokens, Components and Patterns.