# Imani Design System Rules All Imani UI must consume the generated design tokens from `generated/variables.css`, `generated/tokens.ts`, or `generated/tailwind-preset.js`. ## Theme - Every Imani web project must support light, dark, and system color modes with class-based theming. - Never hardcode brand colors. Use generated CSS variables or TypeScript token constants. - Separate brand primitives from application design-system colors: brand tokens identify Imani, while surface, text, border, state, and chart tokens build product UI. - Dark mode must use --color-surface-brand-dark, --color-surface-brand-dark-raised, --color-surface-brand-dark-elevated, and --color-surface-popover-dark rather than reusing Fence Green everywhere. - Aqua Bliss is an accent, focus, and callout color. Do not use it as the page background. - Body copy on light surfaces must be Fence Green or Black Feather, never Tunic Green. - Use Tunic Green for primary actions and active states. ## Assets - Never redraw the Imani logo in code. - Use favicon-real.svg for the mark. - Use imani-logotype-light.svg on light surfaces. - Use imani-logotype.svg on dark surfaces. - Run bun run assets:brand after changing source logo SVGs. ## Component Rules - **button**: Use component.button tokens for height, radius, padding, color, hover, and active states. - **input**: Use component.input tokens for height, border, focus, background, placeholder, and text. - **card**: Use component.card tokens for background, padding, border, radius, and promo accents. - **badge**: Use component.badge tokens and reserve all-caps for compact status labels only. - **overlay**: Use component.overlay tokens for dialogs, popovers, sheets, drawers, and menus. Overlay rows must be at least 40px tall with 12px+ horizontal padding. - **control**: Use component.control tokens for checkbox, radio, switch, slider, toggle, and segmented state styling. - **navigation**: Use component.navigation tokens for tabs, menus, breadcrumbs, pagination, command, and navigation menu states. - **sidebar**: Use component.sidebar tokens for sidebar width, collapsed width, surfaces, and borders. - **chart**: Use component.chart tokens for chart colors, grid lines, and bar radius. - **empty**: Use component.empty tokens for empty states and no-data messaging. - **layout**: Use component.layout tokens for section padding, grids, and repeatable card grid sizing. ## Source Token Files - `tokens/colors.json` - `tokens/typography.json` - `tokens/spacing.json` - `tokens/radius.json` - `tokens/shadows.json` - `tokens/components.json`