# Burraga design system 2.0.0

Read this document before UI work, together with AGENTS.md. Existing projects keep their recorded version. Upgrades require reviewed code changes.

## React components

The reviewed MIT subset from Untitled UI is vendored under react/: buttons, inputs (including labels and hints), badges and tooltip dependencies. upstream.json records the exact source commit and hashes; preserve react/LICENSE. PRO components and other upstream components are not included. Do not fetch latest components during project generation.

Generated web projects use React, TypeScript, Tailwind CSS and React Aria. Import components from @/components/base/ and use their documented props; do not replace them with ad hoc controls. Add an explicit accessible label to inputs and icon-only actions. Do not disable keyboard or focus behavior. User content must remain escaped.

## Burraga foundations

Use tokens.json/tokens.css for brand, typography, spacing, radius and semantic states. The React starter maps Burraga primary colours to the upstream theme. Keep data-theme (light/dark) synchronized with dark-mode; system follows prefers-color-scheme. Test contrasts for every new component or variant; upstream availability is not proof of accessibility.

The existing Factory is a semantic HTML/JavaScript application and uses components.css as the v2 adapter: buttons, forms, cards, badges, tables, dialogs, status panels and responsive layout. It is not a React conversion. The React starter exercises actual upstream components. Native mobile consumes tokens and native controls; no native component implementation is included.

## Agent instructions

Codex, Claude and Lovable must reuse this pinned component vocabulary, preserve the selected version and avoid introducing another design system. Application behavior, permissions and scope still require their usual approvals. Run npm run design-system:check, npm test and npm run build for React projects. Check keyboard use, narrow layouts and both themes. A starter build is not production approval.

## Changes and provenance

Do not edit react/ without a reviewed upstream or local adaptation record. Keep attribution and update manifest/hash pins only as part of a versioned release. License review is required for separately licensed assets. Factory upgrades never rewrite Shift, Hitloop or other existing repositories.