llms.txt

# CUBE CSS Design System

> A minimal CSS design system using CSS Layers, inspired by CUBE CSS methodology

## Overview

CUBE CSS is a layered CSS design system that uses `@layer` for specificity control instead of BEM naming or `!important`. It separates raw design tokens from semantic themes, allowing easy theme swapping. Designed for use with Datastar (reserves `data-*` attributes for framework integration).

## Layer Architecture

```css
@layer reset, props, theme, composition, utility, block, exception;
```

| Layer | File | Purpose |
|-------|------|---------|
| reset | 0_reset.css | Minimal normalize |
| props | 1_props.css | Raw design tokens (colors, sizes, shadows, fonts) |
| theme | 2_theme-*.css | Semantic mapping, swappable themes |
| composition | 3_composition.css | Layout primitives |
| utility | 4_utility.css | Single-purpose modifiers |
| block | 5_block.css | Components |
| exception | 6_exception.css | Variants, sizes, states |

## Class Naming Convention

### Layout Classes (Composition + Utility)
Pattern: `composition:variant` + utility modifiers

```html
<div class="flex:stack gap:md align:center">...</div>
<div class="grid:hero gap:xs">...</div>
<div class="flex:cluster gap:sm wrap">...</div>
```

### Component Classes (Block + Exception)
Pattern: `block:variant-exception` + modifier classes

```html
<button class="btn:pri">Primary</button>
<button class="btn:dgr-sm">Small Danger</button>
<button class="btn:pri out">Primary Outline</button>
<span class="chip:inf-sm">Info Small</span>
```

## Components

### Buttons
- Base: `btn:pri`, `btn:sec`, `btn:wrn`, `btn:dgr`
- Sizes: `-sm`, `-lg` suffix (e.g., `btn:pri-sm`)
- Modifiers: `out` (outline style)

### Icon Buttons
- Base: `icon-btn`, `icon-btn:mute`
- Sizes: `-sm` suffix

### Chips/Tags
- Base: `chip`, `chip:inf`, `chip:suc`, `chip:wrn`, `chip:dgr`
- Sizes: `-sm` suffix

### Badges
- Base: `badge`, `badge:suc`, `badge:wrn`, `badge:dgr`
- Dot variant: `-dot` suffix

### Cards
- Base: `.card`
- Variants: `.pri`, `.sec`, `.gla` (glass)
- Alert cards: `card:alert` with `.inf`, `.suc`, `.wrn`, `.dgr`

### Tabs
- Container: `tabs`, `tabs:pri`, `tabs:sec`
- Items: `tab`, `tab:active`
- Exceptions: `-sm` suffix for small size (e.g., `tabs:pri-sm`)
- Modifiers: `full` standalone class for full-width (e.g., `tabs:pri full`)

**Datastar Active State (Recommended):**
Use signals for reactive tab switching instead of manual class toggling:

```html
<div class="tabs:pri" data-init="$mytab='first'">
  <button class="tab" 
    data-class:tab:active="$mytab=='first'" 
    data-on:click="$mytab='first'">First</button>
  <button class="tab" 
    data-class:tab:active="$mytab=='second'" 
    data-on:click="$mytab='second'">Second</button>
</div>
```

- `data-init` sets the default active tab signal
- `data-class:tab:active` reactively applies the active class
- `data-on:click` updates the signal on click

**Tabs in Forms:**
Tabs work inside `.form` with `field:w*` classes, matching input height automatically:

```html
<label class="field:w2">
  Status
  <div class="tabs" data-init="$status='draft'">
    <button type="button" class="tab" data-class:tab:active="$status=='draft'" data-on:click="$status='draft'">Draft</button>
    <button type="button" class="tab" data-class:tab:active="$status=='published'" data-on:click="$status='published'">Published</button>
  </div>
</label>
```

Validation states (`.err`, `.suc`, `.wrn`, `.inf`) can be applied to the tabs container.

### Popups
- Base: `popup`, `popup:menu`
- Items: `.popup-item`

### Dialogs & Drawers
- Directions: `drawer:left`, `drawer:right`, `drawer:top`, `drawer:bottom`
- Top/bottom drawers: auto-size to content (`height: max-content`), max 90vh, scrollable
- Left/right drawers: fixed height 100vh with configurable width
- Corner rounding: only inner edges (e.g., left drawer rounds top-right & bottom-right)

**Datastar Integration:**

Use `data-ref` with kebab-case (auto-converts to camelCase signal):

```html
<!-- Define dialog with ref and click-outside-to-close -->
<dialog data-ref:my-dialog
        data-on:click="evt.target === el && el.close()">
  <div class="card flex:stack gap:sm p:md">
    <h2>Dialog Title</h2>
    <button data-on:click="el.closest('dialog').close()">Close</button>
  </div>
</dialog>

<!-- Drawer example -->
<dialog data-ref:my-drawer class="drawer:left"
        data-on:click="evt.target === el && el.close()">
  <div class="flex:stack gap:sm p:md">
    <button data-on:click="el.closest('dialog').close()">Close</button>
  </div>
</dialog>

<!-- Open using camelCase signal -->
<button data-on:click="$myDialog.showModal()">Open Dialog</button>
<button data-on:click="$myDrawer.showModal()">Open Drawer</button>
```

**Important:** HTML attributes are case-insensitive, so use kebab-case in `data-ref:my-drawer` which Datastar converts to `$myDrawer`. Using `data-ref:myDrawer` directly won't work.

### Forms
- Container: `.form` (4-column grid)
- Fields: `field` (default full width), `field:w1`, `field:w2`, `field:w3`
- Use `<label class="field">` for inputs, `<div class="field">` for tabs (avoids click propagation)
- Feedback: `<span>` inside field, validation via span class
- Validation states: `.suc`, `.wrn`, `.dgr` (on span)

```html
<form class="form">
  <label class="field">
    Email <span class="dgr">Already registered</span>
    <input type="email" required>
  </label>
  <div class="field:w2">
    Status <span class="wrn">Required</span>
    <div class="tabs" data-init="$status='pending'">
      <button class="tab" data-class:tab:active="$status=='pending'" data-on:click="$status='pending'">Pending</button>
      <button class="tab" data-class:tab:active="$status=='active'" data-on:click="$status='active'">Active</button>
    </div>
  </div>
</form>
```

## Layout Compositions

Structural primitives — the "what" of layout. Use without utilities in demos; add utilities to tune.

### Flex
| Class | Purpose |
|-------|---------|
| `flex:stack` | Vertical column |
| `flex:cluster` | Wrapping horizontal row |
| `flex:split` | Space-between with center alignment |
| `flex:split-col` | Vertical split |
| `flex:flank-start` | First child sidebar, second fills |
| `flex:flank-end` | First child fills, last child sidebar |
| `flex:spread-row` | Horizontal space-between |
| `flex:spread-column` | Vertical space-between |

**Custom Properties:**
- `--flank-size` — sidebar width (default: auto)
- `--content-percentage` — min content width (default: 50%)

### Grid
| Class | Purpose |
|-------|---------|
| `grid:hero` | Holy grail (header/nav/main/aside/footer) |
| `grid:lcr` | Left-center-right columns |
| `grid:tmb` | Top-middle-bottom rows |
| `grid:pancake` | auto/1fr/auto rows |
| `grid:auto-fit` | Responsive, collapses empty tracks |
| `grid:auto-fill` | Responsive, keeps empty tracks |

**Custom Properties:**
- `--grid-min` — minimum column width for auto-fit/fill (default: 250px)

### Frame (Aspect Ratio)
| Class | Ratio |
|-------|-------|
| `frame` | 1:1 (square) |
| `frame:landscape` | 16:9 |
| `frame:portrait` | 9:16 |

### Fullscreen
- `fullscreen` — 100svh, no margin/padding, hidden overflow

## Layout Utilities

Modifiers for compositions — the "how" of tuning layouts. Use sparingly at the composition level, not on every element. Blocks define their own spacing.

### Gap (spacing between children)
`gap:xs`, `gap:sm`, `gap:md`, `gap:lg`, `gap:xl`

### Alignment (cross-axis)
`align:start`, `align:end`, `align:center`, `align:stretch`, `align:baseline`

### Justify (main-axis)
`justify:start`, `justify:end`, `justify:center`, `justify:between`, `justify:around`, `justify:evenly`

### Padding
`p:xs`, `p:sm`, `p:md`, `p:lg`, `p:xl`

> Use for layout containers before blocks are added. Blocks have their own padding.

### Margin
`m:xs`, `m:sm`, `m:md`, `m:lg`, `m:xl`

> Use sparingly — prefer gap for spacing between siblings.

### Scroll
`scroll-y`, `scroll-x`, `scroll-xy`, `scroll-no`

### Wrap
`wrap`, `nowrap`

### Width Constraints
| Class | Max-width |
|-------|-----------|
| `width-sm` | 900px (centered) |
| `width-md` | 1200px (centered) |
| `width-lg` | 100% |

### Text Size
`text:xs`, `text:sm`, `text:md`, `text:lg`, `text:xl`

### Responsive Visibility
- `.desktop` — hidden on ≤768px
- `.mobile` — hidden on >768px

## Design Tokens

### Colors (OKLCH scale 0-9)
- Gray: `--gry-0` to `--gry-9`
- Red: `--red-0` to `--red-9`
- Blue: `--blu-0` to `--blu-9`
- Green: `--grn-0` to `--grn-9`
- Yellow: `--yel-0` to `--yel-9`
- Plus: pink, grape, violet, indigo, cyan, teal, lime, orange

### Semantic Colors (theme layer)
- `--color-pri`, `--color-sec` - brand colors
- `--color-inf`, `--color-suc`, `--color-wrn`, `--color-dgr` - status colors

### Spacing (t-shirt sizes)
- `--space-xs`, `--space-sm`, `--space-md`, `--space-lg`, `--space-xl`

### Surfaces (Well-Based Elevation System)

The surface system uses CSS `:has()` to detect nesting depth automatically. Deepest containers get the darkest shade; leaf surfaces (containing no other surfaces) get the lightest shade making content easiest to read.

**How it works:**
1. Card variants (`card.pri`, `card.sec`) set `--_surface-base`
2. `.surface` elements inherit and auto-lighten based on nesting depth
3. Maximum depth: 3 levels 

**Tokens:**
- `--surface-1` Deepest surface (page level)
- `--surface-2` Mid elevation
- `--surface-3` Content surface (lightest)
- `--_surface-base` Set by card variants; surfaces lighten from this

**Classes:**
- `.surface` Background from `--_surface-base`, auto-lightens based on nesting
- `.shadow` Adds `--shadow-md` box-shadow for depth cues

**Usage:**
```html
<!-- Card sets the surface base -->
<div class="card pri">
  <div class="surface shadow">Leaf surface</div>
</div>

<!-- Nested surfaces auto-elevate -->
<div class="card sec">
  <div class="surface">
    Parent (darker)
    <div class="surface">Leaf (lighter)</div>
  </div>
</div>
```

**Real-world example:** Calendar with year > month > day hierarchy where each level auto-adjusts its shade.

### Other Surface Tokens
- `--surface-page`, `--surface-card`, `--surface-raised`
- `--surface-inset`, `--surface-input`, `--surface-btn`

### Typography
- Sizes: `--text-xs` through `--text-3xl`
- Fonts: Various system font stacks (humanist, monospace, etc.)

## Theme Swapping

Themes are single CSS files. Switch by changing the stylesheet link:

```html
<link rel="stylesheet" href="./css/2_theme-default.css">
<link rel="stylesheet" href="./css/2_theme-sahara.css">
<link rel="stylesheet" href="./css/2_theme-tokyo.css">
<link rel="stylesheet" href="./css/2_theme-cyber.css">
```

With Datastar:
```html
<link rel="stylesheet" data-attr:href="$prst_theme">
```

## Page Layout Pattern

Default holy grail structure using hero grid:

```html
<body class="fullscreen scroll-no">
  <div class="grid:hero gap:xs">
    <header>...</header>
    <nav class="desktop">...</nav>
    <main class="scroll-y">...</main>
    <aside>...</aside>
    <footer>...</footer>
  </div>
</body>
```

- Nav/aside use `<dialog popover>` drawers on mobile
- No z-index tracking needed (popover uses top-layer)
- 4-column forms work without media queries

## Datastar Integration

- Theme/mode switching via signals and `data-attr`
- Partial loading: `data-init="@get('./partials/nav.html')"`
- Signal persistence: `data-persist`
- `data-*` reserved for Datastar (exceptions use class selectors)

## Available Themes

- `2_theme-default.css` - Cool gray-green forest/mist palette
- `2_theme-sahara.css` - Warm desert tones
- `2_theme-tokyo.css` - Urban/tech aesthetic
- `2_theme-cyber.css` - Cyberpunk colors

## Documentation Pages

- index.html - Readme/overview
- colors.html - Color palette reference
- layout.html - Layout compositions (flex, grid, frame)
- layout_utility.html - Layout utilities (gap, align, justify, padding)
- button.html - Button component
- icon_btn.html - Icon button
- chips.html - Chip/tag component
- badge.html - Badge component
- tabs.html - Tab component
- cards.html - Card component
- surface.html - Surface styles
- popup.html - Popup/dropdown
- dialogs.html - Dialogs and drawers
- hr.html - Dividers
- forms.html - Form layout and inputs
- demos.html - Full page demos

## Key Principles

1. **Layered cascade** - `@layer` eliminates specificity wars
2. **Static props, semantic themes** - Swap one file to restyle everything
3. **Exceptions use classes** - Reserves `data-*` for Datastar
4. **Intrinsic sizing** - Minimal media queries, uses auto-fit/fill
5. **Light/dark mode** - Uses `light-dark()` CSS function