@matteoaliano/forest-ui 0.2.9 → 0.2.11

package/guidelines/FOREST_AI_GUIDELINES.md

@@ -1,344 +0,0 @@
-# Forest UI — AI Development Guidelines
-
-> **forest-ui v0.2.9**
-
-> **This file is auto-generated from the `forest-ui` package.**
-> Run `npx forest-ui sync` to update it.
-
----
-
-## 1. Golden Rules
-
-1. **NEVER import from `@mui/material` directly.** Always import from `forest-ui`.
-2. **ALWAYS wrap your app root with `<ForestProvider>`** — it applies the theme and CSS baseline.
-3. **NEVER use inline colors or spacing values.** Use the exported design tokens or MUI's `sx` prop with theme values.
-4. **NEVER create custom component wrappers** for things Forest UI already provides.
-5. **TypeScript is required.** All components export their prop types.
-6. **ALWAYS use the Outlined variant of MUI icons.** Import from `@mui/icons-material/*Outlined` (e.g. `CloseOutlined`, `MailOutlined`). Never use the default (filled), Rounded, Sharp, or TwoTone variants.
-
----
-
-## 2. Installation & Setup
-
-```bash
-npm install @matteoaliano/forest-ui @mui/material @mui/x-data-grid @emotion/react @emotion/styled
-```
-
-```tsx
-// App root — REQUIRED
-import { ForestProvider } from "@matteoaliano/forest-ui";
-
-function App() {
-  return (
-    <ForestProvider>
-      {/* All app content here */}
-    </ForestProvider>
-  );
-}
-```
-
----
-
-## 3. Component Reference
-
-### Import Pattern
-
-```tsx
-// ✅ CORRECT — import from forest-ui
-import { Button, TextField, Alert } from "@matteoaliano/forest-ui";
-
-// ❌ WRONG — never import from @mui/material
-import Button from "@mui/material/Button";
-```
-
-### Available Components
-
-#### Inputs
-| Component | Import | Key Props |
-|-----------|--------|-----------|
-| `Button` | `import { Button } from "@matteoaliano/forest-ui"` | `variant: "contained" \| "outlined" \| "text"`, `size`, `color`, `disabled` |
-| `ButtonGroup` | `import { ButtonGroup } from "@matteoaliano/forest-ui"` | `variant`, `size`, `orientation` |
-| `TextField` | `import { TextField } from "@matteoaliano/forest-ui"` | `variant`, `size`, `label`, `error`, `helperText`, `fullWidth` |
-| `Select` | `import { Select, MenuItem } from "@matteoaliano/forest-ui"` | `label`, `value`, `onChange` |
-| `Checkbox` | `import { Checkbox } from "@matteoaliano/forest-ui"` | `checked`, `onChange`, `disabled` |
-| `RadioGroup` + `Radio` | `import { RadioGroup, Radio } from "@matteoaliano/forest-ui"` | `value`, `onChange`, `row` |
-| `Switch` | `import { Switch } from "@matteoaliano/forest-ui"` | `checked`, `onChange`, `disabled` |
-| `ToggleButton` + `ToggleButtonGroup` | `import { ToggleButton, ToggleButtonGroup } from "@matteoaliano/forest-ui"` | `value`, `exclusive`, `onChange` |
-| `Fab` | `import { Fab } from "@matteoaliano/forest-ui"` | `variant: "circular" \| "extended"`, `size`, `color` |
-| `Autocomplete` | `import { Autocomplete } from "@matteoaliano/forest-ui"` | `options`, `renderInput`, `freeSolo` |
-
-#### Data Display
-| Component | Import | Key Props |
-|-----------|--------|-----------|
-| `Badge` | `import { Badge } from "@matteoaliano/forest-ui"` | `badgeContent`, `color`, `variant: "standard" \| "dot"` |
-| `Chip` | `import { Chip } from "@matteoaliano/forest-ui"` | `label`, `variant: "filled" \| "outlined"`, `onDelete`, `size` |
-| `Divider` | `import { Divider } from "@matteoaliano/forest-ui"` | `orientation`, `variant`, `children` (for text dividers) |
-| `Typography` | `import { Typography } from "@matteoaliano/forest-ui"` | `variant: "h1"-"h6" \| "subtitle1" \| "body1" \| "caption" \| "overline"` |
-| `Tooltip` | `import { Tooltip } from "@matteoaliano/forest-ui"` | `title`, `placement`, `arrow` |
-| `Table` family | `import { Table, TableHead, TableBody, TableRow, TableCell, TableContainer } from "@matteoaliano/forest-ui"` | Standard table composition |
-| `DataGrid` | `import { DataGrid, type GridColDef } from "@matteoaliano/forest-ui"` | `rows`, `columns`, `paginationModel`, `sortModel`, `filterModel`. Requires `@mui/x-data-grid` peer dep |
-| `List` family | `import { List, ListItem, ListItemButton, ListItemIcon, ListItemText, ListItemAvatar, ListSubheader } from "@matteoaliano/forest-ui"` | Standard list composition |
-
-#### Surfaces
-| Component | Import | Key Props |
-|-----------|--------|-----------|
-| `Accordion` family | `import { Accordion, AccordionSummary, AccordionDetails, AccordionActions } from "@matteoaliano/forest-ui"` | `expanded`, `onChange`, `disabled` |
-| `AppBar` + `Toolbar` | `import { AppBar, Toolbar } from "@matteoaliano/forest-ui"` | `position`, `color`, `elevation` |
-| `Card` family | `import { Card, CardContent, CardHeader, CardActions, CardMedia } from "@matteoaliano/forest-ui"` | `variant`, `elevation` |
-| `Paper` | `import { Paper } from "@matteoaliano/forest-ui"` | `variant`, `elevation`, `square` |
-
-#### Feedback
-| Component | Import | Key Props |
-|-----------|--------|-----------|
-| `Alert` + `AlertTitle` | `import { Alert, AlertTitle } from "@matteoaliano/forest-ui"` | `severity: "success" \| "info" \| "warning" \| "error"`, `variant` |
-| `Dialog` family | `import { Dialog, DialogTitle, DialogContent, DialogActions, DialogContentText } from "@matteoaliano/forest-ui"` | `open`, `onClose` |
-| `Backdrop` | `import { Backdrop } from "@matteoaliano/forest-ui"` | `open`, `onClick` |
-| `LinearProgress` | `import { LinearProgress } from "@matteoaliano/forest-ui"` | `variant: "indeterminate" \| "determinate"`, `value` |
-| `CircularProgress` | `import { CircularProgress } from "@matteoaliano/forest-ui"` | `variant: "indeterminate" \| "determinate"`, `value` |
-| `Skeleton` | `import { Skeleton } from "@matteoaliano/forest-ui"` | `variant: "text" \| "circular" \| "rectangular" \| "rounded"`, `width`, `height` |
-| `Snackbar` | `import { Snackbar } from "@matteoaliano/forest-ui"` | `open`, `autoHideDuration`, `onClose`, `message` |
-
----
-
-## 4. Theme & Design Tokens
-
-### Accessing Tokens
-
-```tsx
-// Method 1: Via the sx prop (preferred)
-<Box sx={{ p: 2, borderRadius: 2, color: "text.primary" }} />
-
-// Method 2: Import raw token values (rare, for edge cases)
-import { colors, spacing, radius } from "@matteoaliano/forest-ui";
-
-// Method 3: Import semantic tokens (text, bg, fg, border)
-import { text, bg, fg, border } from "@matteoaliano/forest-ui";
-```
-
-### Color Palette
-
-| Token | Value | Usage |
-|-------|-------|-------|
-| `primary.main` | `#7f56d9` (brand.600) | Primary actions, links, active states |
-| `primary.light` | `#b692f6` (brand.400) | Hover states |
-| `primary.dark` | `#6941c6` (brand.700) | Pressed states |
-| `secondary.main` | `#475467` (gray.600) | Secondary actions |
-| `error.main` | `#d92d20` (error.600) | Destructive actions, error states |
-| `warning.main` | `#dc6803` (warning.600) | Warnings |
-| `success.main` | `#079455` (success.600) | Success states |
-| `info.main` | `#1570ef` (blue.600) | Informational |
-| `text.primary` | `#101828` (gray.900) | Main text |
-| `text.secondary` | `#344054` (gray.700) | Supporting text |
-| `background.default` | `#ffffff` | Page background |
-| `background.paper` | `#ffffff` | Card/surface background |
-| `divider` | `#eaecf0` (gray.200) | Borders and dividers |
-
-### Spacing Scale
-
-Use the MUI spacing multiplier: `theme.spacing(1) = 4px`
-
-| Token | px | Usage |
-|-------|-----|-------|
-| `spacing(1)` | 4px | Tight gaps |
-| `spacing(2)` | 8px | Component internal padding |
-| `spacing(3)` | 12px | Small gaps |
-| `spacing(4)` | 16px | Standard section spacing |
-| `spacing(6)` | 24px | Medium section spacing |
-| `spacing(8)` | 32px | Large section spacing |
-
-### Border Radius
-
-| Token | Value | Usage |
-|-------|-------|-------|
-| `borderRadius: 1` | 4px | Small elements (chips, badges) |
-| `borderRadius: 2` | 8px | Buttons, inputs |
-| `borderRadius: 3` | 12px | Cards, dialogs |
-
-### Semantic Tokens
-
-Forest UI exports semantic color maps for precise control beyond the MUI palette:
-
-| Export | Purpose | Example keys |
-|--------|---------|-------------|
-| `text` | Text colors | `primary`, `secondary`, `tertiary`, `disabled`, `brandPrimary`, `errorPrimary` |
-| `bg` | Background colors | `primary`, `secondary`, `brandSolid`, `errorPrimary`, `overlay` |
-| `fg` | Foreground/icon colors | `primary`, `secondary`, `brandPrimary`, `errorPrimary`, `disabled` |
-| `border` | Border colors | `primary`, `secondary`, `brand`, `brandSolid`, `error` |
-| `buttonColors` | Button variants | `primary`, `secondary`, `secondaryColor`, `tertiary`, `primaryError` |
-| `chartColors` | Chart/data viz | `series1Fg`, `series2Fg`, `axisFg`, `tooltipBg` |
-
-### Preset System
-
-For advanced theming, Forest UI supports presets — named theme variants built from a full `DesignTokens` object:
-
-```tsx
-import { ForestProvider, buildTheme, registerPreset } from "@matteoaliano/forest-ui";
-
-// Use a preset by name
-<ForestProvider preset="forest" variant="light">
-  {children}
-</ForestProvider>
-
-// Or build a custom theme from tokens
-const customTheme = buildTheme(myDesignTokens);
-<ForestProvider theme={customTheme}>
-  {children}
-</ForestProvider>
-```
-
----
-
-## 5. Code Patterns
-
-### Form Layout
-
-```tsx
-import { TextField, Button, Select, MenuItem, Checkbox } from "@matteoaliano/forest-ui";
-import Box from "@mui/material/Box"; // Box, Stack, Grid are OK from MUI
-
-function ContactForm() {
-  return (
-    <Box sx={{ display: "flex", flexDirection: "column", gap: 3 }}>
-      <TextField label="Name" fullWidth />
-      <TextField label="Email" type="email" fullWidth />
-      <Select label="Subject" fullWidth>
-        <MenuItem value="support">Support</MenuItem>
-        <MenuItem value="sales">Sales</MenuItem>
-      </Select>
-      <Button variant="contained" type="submit">
-        Send
-      </Button>
-    </Box>
-  );
-}
-```
-
-### Data Table
-
-```tsx
-import {
-  Table, TableContainer, TableHead, TableBody, TableRow, TableCell,
-} from "@matteoaliano/forest-ui";
-
-function UsersTable({ users }) {
-  return (
-    <TableContainer>
-      <Table>
-        <TableHead>
-          <TableRow>
-            <TableCell>Name</TableCell>
-            <TableCell>Email</TableCell>
-          </TableRow>
-        </TableHead>
-        <TableBody>
-          {users.map((u) => (
-            <TableRow key={u.id}>
-              <TableCell>{u.name}</TableCell>
-              <TableCell>{u.email}</TableCell>
-            </TableRow>
-          ))}
-        </TableBody>
-      </Table>
-    </TableContainer>
-  );
-}
-```
-
-### DataGrid
-
-```tsx
-import { DataGrid, type GridColDef } from "@matteoaliano/forest-ui";
-
-const columns: GridColDef[] = [
-  { field: "id", headerName: "ID", width: 70 },
-  { field: "name", headerName: "Name", flex: 1 },
-  { field: "email", headerName: "Email", flex: 1 },
-];
-
-function UsersGrid({ rows }) {
-  return <DataGrid rows={rows} columns={columns} />;
-}
-```
-
-### Feedback Pattern
-
-```tsx
-import { Alert, AlertTitle, Snackbar } from "@matteoaliano/forest-ui";
-
-// Inline feedback
-<Alert severity="error">
-  <AlertTitle>Error</AlertTitle>
-  Something went wrong.
-</Alert>
-
-// Toast notification
-<Snackbar open={open} autoHideDuration={4000} onClose={handleClose}>
-  <Alert severity="success" variant="filled">Saved!</Alert>
-</Snackbar>
-```
-
-### Confirmation Dialog
-
-```tsx
-import { Dialog, DialogTitle, DialogContent, DialogActions, DialogContentText, Button } from "@matteoaliano/forest-ui";
-
-function ConfirmDialog({ open, onClose, onConfirm }) {
-  return (
-    <Dialog open={open} onClose={onClose}>
-      <DialogTitle>Confirm</DialogTitle>
-      <DialogContent>
-        <DialogContentText>Are you sure?</DialogContentText>
-      </DialogContent>
-      <DialogActions>
-        <Button variant="outlined" onClick={onClose}>Cancel</Button>
-        <Button onClick={onConfirm}>Confirm</Button>
-      </DialogActions>
-    </Dialog>
-  );
-}
-```
-
----
-
-## 6. Anti-Patterns
-
-```tsx
-// ❌ WRONG: importing from @mui/material
-import Button from "@mui/material/Button";
-
-// ❌ WRONG: hardcoded colors
-<Box sx={{ backgroundColor: "#7f56d9" }} />
-
-// ❌ WRONG: hardcoded spacing
-<Box sx={{ padding: "16px" }} />
-
-// ❌ WRONG: forgetting ForestProvider
-ReactDOM.render(<App />, root); // theme won't apply
-
-// ❌ WRONG: using filled (default) icons
-import CloseIcon from "@mui/icons-material/Close";
-
-// ✅ CORRECT: always use Outlined variant
-import CloseIcon from "@mui/icons-material/CloseOutlined";
-
-// ✅ CORRECT: use theme tokens
-<Box sx={{ backgroundColor: "primary.main", p: 4 }} />
-```
-
-> **Note:** Layout primitives like `Box`, `Stack`, `Grid`, and `Container` should still be imported from `@mui/material` — Forest UI does not re-export these because they have no custom styling.
-
----
-
-## 7. TypeScript Props
-
-Every component exports its props type:
-
-```tsx
-import { Button, type ButtonProps } from "@matteoaliano/forest-ui";
-
-interface MyButtonProps extends ButtonProps {
-  analyticsId: string;
-}
-```
-
-

package/guidelines/FOREST_DEV_GUIDELINES.md

@@ -1,47 +0,0 @@
-# Forest UI — Development Best Practices
-
-> **forest-ui v0.2.9**
-
-> **This file is synced by the `forest-ui` package.**
-> Run `npx forest-ui sync` to update it.
-
----
-
-When generating code or suggesting solutions for Next.js projects, always follow these principles and best practices:
-
-Separation of Concerns
-Maintain a clear separation between presentation logic, business logic, and data management. Organize code into meaningful modules and folders (e.g., pages, components, lib, api).
-
-Single Responsibility Principle
-Each component, hook, or function must have a single, well-defined purpose. Avoid components or modules that handle multiple responsibilities simultaneously.
-
-Clean Code and Naming Conventions
-Write readable code with descriptive names for variables, functions, and components. Use consistent conventions:
-
-camelCase for functions and variables.
-
-PascalCase for components.
-
-kebab-case for files.
-
-Component Reusability
-Build generic and reusable components. Avoid duplicating logic or UI. If a pattern repeats, consider extracting it into a shared component.
-
-Consistent Data Flow
-Maintain a clear and predictable data flow (top-down). If necessary, use the Context API or global states carefully, documenting the flow.
-
-Predictable States
-Manage states clearly and consistently. Use useState, useReducer, or global state libraries (like Zustand or Redux) only when necessary, ensuring every change is traceable and understandable.
-
-Final Output
-The generated code must be:
-
-Readable and easily maintainable.
-
-Compliant with Next.js conventions.
-
-Easily testable.
-
-Integratable into an existing project without conflicts.
-
-If asked to write code, always include brief but helpful comments explaining what important sections do.

package/guidelines/themes/FOREST_THEME_ALKEMY_PLUS.md

@@ -1,139 +0,0 @@
-# Forest UI — Alkemy+ Theme Guidelines
-
-> **forest-ui v0.2.9**
-
-> **This file is synced by the `forest-ui` package.**
-> Run `npx forest-ui sync` to update it.
-
----
-
-## Theme Overview
-
-The **Alkemy+** preset (`preset="alkemy-plus"`) applies Alkemy+ brand identity on top of the shared Forest layout system. It uses **black as the primary action color** and **red (`#F04040`) as the secondary accent**, with warm-neutral grays. Spacing, radius, typography, and shadows are identical to the default Forest theme.
-
-### Activation
-
-```tsx
-<ForestProvider preset="alkemy-plus">
-  <App />
-</ForestProvider>
-```
-
-Or build a standalone MUI theme:
-
-```ts
-import { alkemyPlusPreset, buildTheme } from "@matteoaliano/forest-ui";
-
-const theme = buildTheme(alkemyPlusPreset.variants.light.tokens);
-```
-
----
-
-## Color Strategy
-
-### Primary = Black
-
-The `colors.brand` scale is a **black/dark neutral ramp**. This means:
-
-- **Primary buttons** (`variant="contained"`) → black background, white text
-- **`palette.primary.main`** → `#1A1A1A`
-- **`bg.brandSolid`** → `#1A1A1A` (dark fills, hero sections)
-
-### Secondary = Red (`#F04040`)
-
-Red is the **accent/highlight** color, used for interactive states and visual emphasis:
-
-- **Focus rings** → red tint
-- **Checkboxes, radios, switches** (checked state) → red
-- **Selected list items, toggle buttons** → red tint background
-- **Outlined accent buttons** (`secondaryColor`) → red text and border
-- **Sliders** → red handle
-- **Brand semantic tokens** (`fg.brandPrimary`, `bg.brandPrimary`, `border.brand`) → red
-
----
-
-## Color Palette
-
-### Brand Scale (Black — Primary)
-
-| Token | HEX | Role |
-|---|---|---|
-| `brand.600` | `#1A1A1A` | Primary buttons, solid fills |
-| `brand.700` | `#0D0D0D` | Hover state for primary actions |
-| `brand.500` | `#404040` | Mid-tone dark |
-| `brand.100` | `#EBEBEB` | Subtle brand backgrounds |
-| `brand.50` | `#F5F5F5` | Lightest brand tint |
-
-### Red Accent (Secondary)
-
-| Token path | HEX | Role |
-|---|---|---|
-| `fg.brandPrimary` | `#DC2626` | Accent foreground (checkboxes, switches, icons) |
-| `bg.brandPrimary` | `#FEF2F2` | Selected/active state background |
-| `border.brand` | `#FCA5A5` | Accent borders (outlined accent buttons) |
-| `border.brandSolid` | `#DC2626` | Strong accent border |
-
-### Gray Scale (Warm Neutrals)
-
-| Token | HEX | Role |
-|---|---|---|
-| `gray.50` | `#FAF9F8` | Page background |
-| `gray.100` | `#F5F3F1` | Tertiary backgrounds |
-| `gray.300` | `#D8D8DC` | Borders |
-| `gray.400` | `#A0A0A6` | Muted foreground |
-| `gray.700` | `#3F3F46` | Secondary text |
-| `gray.900` | `#18181B` | Primary text |
-
-### Accent / Gradient Colors
-
-These colors from the Alkemy+ palette are available for gradients, illustrations, and data visualization but are **not** mapped to semantic tokens:
-
-| Name | HEX | Suggested Use |
-|---|---|---|
-| Magenta | `#D83070` | Gradients, decorative accents |
-| Violet | `#7040C8` | Gradients, chart series |
-| Orange | `#F08828` | Gradients, chart series |
-| Yellow | `#F0C800` | Gradients, highlights |
-| Muted Pink | `#D89898` | Soft accents, illustration fills |
-
-### Functional Colors
-
-| Status | Source | Notes |
-|---|---|---|
-| **Error** | Forest defaults (red) | Standard UX — unchanged |
-| **Warning** | Orange scale (`#F08828` base) | Alkemy+ orange/yellow tones |
-| **Success** | Forest defaults (green) | Standard UX — unchanged |
-| **Info (blue)** | Forest defaults (blue) | Standard UX — unchanged |
-
----
-
-## Background Usage
-
-Background tokens follow the same hierarchy as the default Forest theme. The only visual difference is the **warm undertone** in gray surfaces.
-
-| Context | Token | Value |
-|---|---|---|
-| Page background | `bg.primary` | `#FAF9F8` (warm Gray 50) |
-| Elevated surface | `bg.secondary` | `#FFFFFF` |
-| Inset | `bg.tertiary` | `#F5F3F1` (warm Gray 100) |
-| Brand solid | `bg.brandSolid` | `#1A1A1A` (brand 600 — black) |
-| Brand section | `bg.brandSection` | `#050505` (brand 800 — near-black) |
-| Accent tint | `bg.brandPrimary` | `#FEF2F2` (red 50 — subtle red) |
-
-> [!IMPORTANT]
-> Always use semantic tokens (`bg.primary`, `bg.brandSolid`, etc.) — never hard-code hex values. This ensures correct rendering across all theme presets.
-
----
-
-## Key Differences from Default Theme
-
-| Aspect | Default (Forest) | Alkemy+ |
-|---|---|---|
-| Primary action | Purple (`#7F56D9`) | Black (`#1A1A1A`) |
-| Accent / secondary | Purple (same as primary) | Red (`#F04040`) |
-| Gray tone | Cool blue-gray | Warm neutral |
-| Warning palette | Amber/gold | Orange (`#F08828` base) |
-| Focus rings | Purple tint | Red tint |
-| Layout & spacing | Shared | Shared |
-| Typography | Poppins | Poppins |
-| Shadows | Shared | Shared |

package/guidelines/themes/FOREST_THEME_DEFAULT.md

@@ -1,70 +0,0 @@
-# Forest UI — Default Theme Guidelines
-
-> **forest-ui v0.2.9**
-
-> **This file is synced by the `forest-ui` package.**
-> Run `npx forest-ui sync` to update it.
-
----
-
-## Background Usage
-
-### Page & Layout Defaults
-
-| Context | Token | Value | Usage |
-|---|---|---|---|
-| **Page background** | `bg.primary` | `#f9fafb` (Gray 50) | Default background for every page and top-level layout. All root containers (`<body>`, app shell, page wrappers) must use this token. |
-| **Page background (alt)** | `bg.primaryAlt` | `#f9fafb` (Gray 50) | Alias available when a future theme overrides the primary page bg. Use interchangeably with `bg.primary` in layouts. |
-
-> [!IMPORTANT]
-> Every page **must** set its root background to `bg.primary`. Never hard-code `#f9fafb` or any other color — always reference the semantic token so themes can override it.
-
-### Surface Hierarchy
-
-Use progressively deeper background tokens to create visual depth between nested surfaces:
-
-| Level | Token | Typical Use |
-|---|---|---|
-| 0 — Page | `bg.primary` | Page canvas, app shell |
-| 1 — Elevated surface | `bg.secondary` / `bg.secondaryAlt` | Cards, papers, sidebar panels — white surfaces that sit on top of the gray page canvas |
-| 1 — Section (subtle) | `bg.secondarySubtle` | Very light tinted sections (e.g., feature highlight rows) |
-| 2 — Inset | `bg.tertiary` | Nested panels, code blocks, table header rows |
-| 3 — Deepest inset | `bg.quaternary` | Skeleton loaders, deeply nested containers |
-
-### Interactive & State Backgrounds
-
-| Token | When to Use |
-|---|---|
-| `bg.primaryHover` | Hover state for items sitting on a `bg.primary` surface (e.g., table rows, list items) |
-| `bg.secondaryHover` | Hover state for items on a `bg.secondary` surface |
-| `bg.active` | Currently active/selected row or item |
-| `bg.disabled` | Disabled inputs, cards, or interactive areas |
-| `bg.disabledSubtle` | Lighter disabled state (e.g., toggle tracks, secondary disabled surfaces) |
-
-### Brand Backgrounds
-
-| Token | When to Use |
-|---|---|
-| `bg.brandPrimary` / `bg.brandPrimaryAlt` | Subtle brand-tinted surfaces (e.g., selected chip, promotion banner) |
-| `bg.brandSecondary` | Slightly stronger brand tint (e.g., badge background, accent panel) |
-| `bg.brandSolid` | Solid brand fill (e.g., primary CTA background) |
-| `bg.brandSolidHover` | Hover state for `bg.brandSolid` elements |
-| `bg.brandSection` / `bg.brandSectionSubtle` | Full-width brand sections (e.g., hero, footer band) |
-
-### Feedback / Status Backgrounds
-
-| Status | Primary | Secondary | Solid |
-|---|---|---|---|
-| Error | `bg.errorPrimary` | `bg.errorSecondary` | `bg.errorSolid` |
-| Warning | `bg.warningPrimary` | `bg.warningSecondary` | `bg.warningSolid` |
-| Success | `bg.successPrimary` | `bg.successSecondary` | `bg.successSolid` |
-
-- **Primary** — subtle tinted banners and alert backgrounds
-- **Secondary** — slightly stronger tint for emphasis
-- **Solid** — filled badges, toasts, or status dots
-
-### Overlay
-
-| Token | When to Use |
-|---|---|
-| `bg.overlay` | Scrim behind modals and drawers (use with alpha transparency) |