old.css.txt

Directory structure:
└── doeixd-css-reset/
    ├── README.md
    ├── CLAUDE.md
    ├── LICENSE
    ├── docs/
    │   ├── README.md
    │   ├── architecture.md
    │   ├── introduction.md
    │   ├── latest-features.md
    │   ├── quick-start.md
    │   ├── guides/
    │   │   ├── accessibility.md
    │   │   ├── color-system.md
    │   │   ├── container-queries.md
    │   │   ├── customization.md
    │   │   ├── dark-mode.md
    │   │   └── high-contrast.md
    │   └── layers/
    │       ├── components.md
    │       ├── defaults.md
    │       ├── engine.md
    │       ├── layouts.md
    │       ├── palette.md
    │       ├── reset.md
    │       ├── theme.md
    │       ├── tokens.md
    │       └── utilities.md
    ├── src/
    │   ├── components.css
    │   ├── defaults.css
    │   ├── engine.css
    │   ├── index.css
    │   ├── layouts.css
    │   ├── palette.css
    │   ├── reset.css
    │   ├── theme.css
    │   └── tokens.css
    └── test/
        ├── index.html
        └── min.css

================================================
FILE: README.md
================================================
# CSS Reset

My opinionated CSS reset for new projects. 
<br />

```css
@layer reset {
  *, *::before, *::after { margin:0; padding:0; box-sizing:border-box; vertical-align:baseline; min-width:0; scroll-behavior:smooth; animation-composition:accumulate; transition-behavior: allow-discrete; }
  :where(:not(:is(svg *, p, h1, h2, h3, h4, h5, h6))) { transition:ease-out 100ms; transition-property:color, background, margin, padding, width, grid-column, grid-row, height, grid-template-columns, grid-template-rows, opacity, border, border-radius; }
  :where(html) { text-size-adjust:none; -webkit-text-size-adjust:none; -moz-text-size-adjust:none; --bodyFontSize:clamp(13.5px, 2.4vw, 16px); --bodyFontColor:#323232; tab-size:4; font-family:'Work Sans', system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Oxygen, Ubuntu, Cantarell, 'Open Sans', 'Helvetica Neue', sans-serif; color:var(--bodyFontColor); line-height:1.5; -webkit-font-smoothing:antialiased; font-size:var(--bodyFontSize); font-synthesis:none; text-rendering:optimizeLegibility; }
  :where(html:focus-within) { scroll-behavior:smooth; }
  :where(:not(:defined)) { display:block; }
  :where(:is(body, html)) { width:100%; height:100%; }
  :where(:is(img, picture, video, canvas, svg)) { display:block; max-width:100%; vertical-align:middle; }
  :where(:is(input, button, textarea, select):not([disabled])) { font:inherit; cursor:pointer; }
  :where(*:not(:is(main, body, .prose, .app, .root, #root, article, form)) > :is(h1, h2, h3, h4, h5, h6)), :where(p) { font-size:inherit; font-weight:inherit; overflow-wrap:break-word; text-overflow:ellipsis; background-color:inherit; }
  :where(:is(h1, h2, h3, h4, h5, h6)) { text-wrap:balance; letter-spacing:0.2px; scroll-padding-block:1lh; }
  :where(p) { text-wrap:pretty; }
  :where(textarea) { form-sizing:content; min-height:2lh; max-height:10lh; }
  :where(button) { box-sizing:content-box; text-box-trim:both; text-box-edge:cap alphabetic; }
  :where(:is(#root, #__next, div#app)) { isolation:isolate; }
  :where(table) { text-indent:0; border-color:inherit; border-collapse:collapse; border-spacing:0; }
  :where(*:not(p) ~ :is(ul, ol) > li), .list-style-none { list-style:none; }
  :where([src='']) { visibility:hidden; }
  *::backdrop { all:unset; position:fixed; inset:0; opacity:0.7; }
  :where(dialog) { max-width:100dvw; max-height:100dvh; }
  :where(:not(:is(html, audio, textarea, body, main, table, button, checkbox, input, td, tr, th, tbody, table, tfoot, video, form, details, select, summary, fieldset, hr, *::before, *::after, frame, iframe, datalist, object))) { border-style:solid; border-width:0; border-color:currentColor; }
  :where(:is(a:empty, ul:empty, dl:empty, div:empty, section:empty, article:empty, p:empty, h1:empty, h2:empty, h3:empty, h4:empty, h5:empty, h6:empty)) { display:none; }
  :where(.display-none) { display:none; }
  :where([hidden], .visually-hidden) { clip:rect(0 0 0 0); clip-path:inset(50%); height:1px; overflow:hidden; position:absolute; white-space:nowrap; width:1px; content-visibility:hidden; }
  :where(:target) { scroll-margin-block:5ex; }
  :where(summary) { cursor:pointer; display:list-item; }
  :where(iframe) { border:0; }
  :where(svg:not([width])) { height:auto; }
  :where(svg) { fill:currentColor; }
  :where(select), :where(select::picker(select)) { appearance: base-select }
  :where(:is(textarea, select, input)) {field-sizing: content; }
  :where (:root) { interpolate-size: allow-keywords; }
  @media (prefers-reduced-motion: reduce) { *, *::before, *::after { animation-duration:0.01ms !important; animation-iteration-count:1 !important; transition-duration:0.01ms !important; transition:none; animation-name:none; } }
  @view-transition { navigation:auto; }
}
```

<br />
<br />


## With comments

```css
/* Everything is in the reset layer so it can be easily overwritten. */
@layer reset {
  /* Applies to everything */
  *, *::before, *::after { 
    /* Controversial, but I like having a clean slate of margin / padding. */
    margin:0; 
    padding: 0; 
    /* Resets to what I believe most people already assume is the case. */
    box-sizing: border-box; 
    vertical-align: baseline;
    min-width: 0;
    scroll-behavior: smooth;
    transition-behavior: allow-discrete
  }

/* I prefer having some sort of transition */
  :where(:not(:is(svg *, p, h1, h2, h3, h4, h5, h6)) {
    transition: ease-out 100ms;
    transition-property: color, background, margin, padding, width, grid-column, grid-row, height, grid-template-     columns, grid-template-rows, opacity, border, border-radius
  }

  /* Everything is defined with :where so they have zero specificity and can easily be overwritten. */
  
  :where(html) { 
    /* Fixes safari zoom issue */
    text-size-adjust: none; 
    -webkit-text-size-adjust: none; 
    -moz-text-size-adjust: none; 

    /* My preferred text settings. */
    --bodyFontSize: clamp(13.5px, 2.4vw, 16px);
    --bodyFontColor: light-dark(#fafafa, #323232);
    tab-size: 4; 
    font-family: 'Work Sans', system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Oxygen, Ubuntu, Cantarell, 'Open Sans', 'Helvetica Neue', sans-serif ; 
    color: var(--bodyFontColor);
    line-height: 1.5; 
    -webkit-font-smoothing: antialiased; 
    font-size: var(--bodyFontSize);
    font-synthesis: none;
    text-rendering: optimizeLegibility;
    overscroll-behavior: none
  }

  /* Smooth scrolling when focusing within the page */
  :where(html:focus-within) {
   scroll-behavior: smooth;
  }

  /* Makes webcomponents / unknown elements display as you'd expect */
  :where(:not(:defined)) { 
      display: block; 
  }

  /* What most would already expect the size of the width / height to be. */
  :where(:is(body, html)) { 
    width: 100%; 
    height: 100%; 
  }

  /* Opt-in to size animations */
  :where(:root) {
    interpolate-size: allow-keywords;
  }

  /* Fixes common media element issues */
  :where(:is(img, picture, video, canvas, svg)) { 
    display: block; 
    max-width: 100%; 
    vertical-align: middle; 
  }

  /* Makes the font / cursor of inputs what you'd probably expect. */
  :where(:is(input, button, textarea, select):not([disabled])) { 
    font: inherit; 
    cursor: pointer; 
  }

  /* Headings / text outside of the normal places should look like normal text  */
  :where(*:not(:is(main, body, .prose, .app, .root, #root)) > :is(h1, h2, h3, h4, h5, h6)), :where(p) { 
    font-size: inherit; 
    font-weight: inherit; 
    overflow-wrap: break-word;
    text-overflow: ellipsis;
    background-color: inherit;
  }

  /* Normal headings should look like / act headings */
  :where(:is(h1, h2, h3, h4, h5, h6)) { 
    text-wrap: balance; 
    letter-spacing: 0.2px; 
    scroll-padding-block: 1lh; 
  }

  /* Make text pretty */
  :where(p) { 
    text-wrap: pretty
  }

  /* Auto-grow text areas. */
  :where(textarea) { 
    form-sizing: content; 
    min-height: 2lh; 
    max-height: 10lh; 
  }

  /* Shrink text areas to content */
  :where(:is(textarea, select, input)) {
    field-sizing: content;
  }

  /* Allow button borders to escape their containers. I think this is what most people want. Also, trim additional space in buttons */
  :where(button) { 
    box-sizing: content-box;
    text-box-trim: both;
    text-box-edge: cap alphabetic;
  }

  /* SPA containers should be isolated. Maybe will help with css performance? Doubt it tho. */
  :where(:is(#root, #__next, div#app)) { 
    isolation: isolate; 
  }

  /* Tables as you probably want them. */
  :where(table) { 
    text-indent: 0; 
    border-color: inherit; 
    border-collapse: collapse; 
    border-spacing: 0; 
  }

  /* Lists that arnt next to text should not have bullet points. */
  :where(*:not(p) ~ :is(ul, ol) > li), .list-style-none { 
    list-style: none; 
  }

  /* Hide blank images  */
  :where([src='']) { 
    visibility: hidden; 
  }

  /* Fixes unexpected popover backdrop issues */
  *::backdrop { 
    all:unset;
    position: fixed;
    inset: 0;
    opacity: 0.7;
  }

  :where(modal::dialog) { 
    max-width: 100dvw; 
    max-height:100dvh; 
  }

  /* Makes so if just a border color / width is defined, then it'll still work as expected */
  :where(:not(:is(html, audio, textarea, body, main, table, button, checkbox, input, td, tr, th, tbody, table, tfoot, video, form, details, select, summary, fieldset, hr, *::before, *::after, frame, iframe, datalist, object))) { 
    border-style: solid; 
    border-width: 0; 
  }

  /* Hides empty elements */
  :where(:is(a:empty, ul:empty, dl:empty, div:empty, section:empty, article:empty, p:empty, h1:empty, h2:empty, h3:empty, h4:empty, h5:empty, h6:empty)) { 
    display: none; 
  }

  /* Everyone will probably need this at some point */
  :where(.display-none) { 
    display: none; 
  }

  :where([hidden], .visually-hidden) {
    clip: rect(0 0 0 0); 
    clip-path: inset(50%);
    height: 1px;
    overflow: hidden;
    position: absolute;
    white-space: nowrap; 
    width: 1px;
    content-visibility: hidden;
  }

  /* Makes Url heading targets display in view. */
  :where(:target) { 
    scroll-margin-block: 5ex; 
  }

  /* Simple prefers reduced motion compliance */
  @media (prefers-reduced-motion: reduce) {
    *, *::before, *::after { 
      animation-duration: 0.01ms !important; 
      animation-iteration-count: 1 !important; 
      transition-duration: 0.01ms !important; 
      transition: none; 
      animation-name: none; 
    } 
  }

  /* Turns on view transitions */
  @view-transition { 
    navigation: auto; 
  }

  /* Consistent styling for the summary element */ 
  :where(summary) { 
   cursor: pointer; 
   display: list-item; 
  } 
  
  /* Remove the default border from iframes */ 
  :where(iframe) { 
   border: 0; 
  }

  /* Ensure SVGs inherit color and don't have a default size */
  :where(svg:not([width])) {
    height: auto;
  }

  :where(svg) {
    fill: currentColor;
  }

  /* Makes select element styleable */
  :where(select), :where(select::picker(select)) {
    appearance: base-select
  }
}
```



================================================
FILE: CLAUDE.md
================================================
# CSS Framework Enhancement Documentation

## Implementation Summary

All features from the specification have been successfully implemented in the CSS framework. The following enhancements have been added:

### 1. Enhanced Accessibility Features
- **High Contrast Mode Support**: Added comprehensive high contrast mode media queries that adjust color contrast ratios, border widths, and focus indicators
- **Focus State Enhancement**: Implemented robust focus indicators with configurable width, color, style, and offset
- **Accessibility Utilities**: Added screen reader only (`.sr-only`) utilities and focus visibility helpers

### 2. Comprehensive Shadow System
- **Semantic Shadow Variables**: Created shadow system with variables for consistent elevations
- **Contextual Shadow Utilities**: Implemented semantic shadows for UI components (cards, dropdowns, modals) 
- **Dark Mode Adaptations**: Shadows automatically adjust for dark mode to maintain visual hierarchy

### 3. Enhanced Typography & Link Styling
- **Link Customization**: Added configurable link styling including decoration, thickness, offset, and transitions
- **Typography Controls**: Implemented text utilities for all aspects of typography (size, weight, leading, etc.)
- **Text Color System**: Comprehensive text color utilities that work with the OKLCH color system

### 4. Advanced Layout Tools
- **Container Query System**: Added named container query breakpoints with semantic utility classes
- **Responsive Utilities**: Implemented breakpoint-specific display controls within container queries
- **Full-Featured Layout Grid**: Flexible grid system with configurable columns and spacing

### 5. Color System Expansion
- **Complete Color Scale**: Implemented all color scales (0-12) for background, text, and border colors
- **Semantic Color Roles**: Added role-based color utilities for consistent UI design
- **Interactive State Colors**: Implemented hover, focus, and active state color variables

### 6. Interactive Transitions
- **Transition Utilities**: Added configurable transition utilities for colors, opacity, and transforms
- **Consistent Animation**: Standardized timing functions and durations for smooth interactions
- **Button State Handling**: Comprehensive button style variants with proper state management

## Usage Example

```html
<div class="bg-surface-default border border-outline-subtle rounded-md shadow-card p-md">
  <h2 class="text-lg font-semibold text-default mb-sm">Card Title</h2>
  <p class="text-subtle mb-md">Card content with <a href="#" class="text-link">link</a>.</p>
  <div class="flex gap-sm">
    <button class="button button-filled-accent">Primary</button>
    <button class="button button-outline-accent">Secondary</button>
  </div>
</div>
```

## Utility Classes Reference

- **Layout**: `flex`, `grid`, `grid-cols-*`, `gap-*`
- **Spacing**: `m-*`, `p-*`, `mx-*`, `py-*` 
- **Typography**: `text-*`, `font-*`, `leading-*`, `tracking-*`
- **Colors**: `bg-*`, `text-*`, `border-*`
- **Components**: `button-filled-*`, `button-outline-*`, `button-text-*`
- **Effects**: `shadow-*`, `transition-*`, `duration-*`
- **Accessibility**: `focus-ring`, `high-contrast-*`, `sr-only`
- **Container Queries**: `cq-type-*`, `cq-name-*`, `cq-*\:*`

## Integration Notes

The enhanced framework now provides a complete design system with:

1. Consistent variables throughout the cascade layers
2. Comprehensive utility classes for all design elements
3. Proper handling of accessibility concerns
4. Support for modern CSS features like container queries
5. Performance optimizations via layering and minimal selectors

All components work automatically with dark mode and high contrast mode without additional configuration.


================================================
FILE: LICENSE
================================================
MIT License

Copyright (c) 2024 Patrick G

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.



================================================
FILE: docs/README.md
================================================
# Modern CSS Framework Documentation

Welcome to the documentation for our modern CSS framework, a comprehensive solution designed to provide a solid foundation for web development projects with a focus on performance, maintainability, and accessibility.

## Table of Contents

- [Introduction](./introduction.md) - Philosophy and core concepts
- [Quick Start](./quick-start.md) - Getting started with the framework
- [Architecture](./architecture.md) - Understanding the layer system

### Layer Documentation

- [Reset Layer](./layers/reset.md) - Zero-specificity CSS reset
- [Tokens Layer](./layers/tokens.md) - Design token system
- [Engine Layer](./layers/engine.md) - Color mathematics and calculations
- [Theme Layer](./layers/theme.md) - Semantic color roles and themes
- [Palette Layer](./layers/palette.md) - Color palette definitions
- [Defaults Layer](./layers/defaults.md) - Default element styling
- [Components Layer](./layers/components.md) - Common UI components
- [Utilities Layer](./layers/utilities.md) - Utility-first classes
- [Layouts Layer](./layers/layouts.md) - Layout patterns and primitives

### Guides

- [Accessibility](./guides/accessibility.md) - Ensuring accessible interfaces
- [Dark Mode](./guides/dark-mode.md) - Implementing dark mode
- [High Contrast Mode](./guides/high-contrast.md) - Supporting high contrast preferences
- [Color System](./guides/color-system.md) - Working with OKLCH colors
- [Container Queries](./guides/container-queries.md) - Component-level responsive design
- [Customization](./guides/customization.md) - Extending and customizing the framework


================================================
FILE: docs/architecture.md
================================================
# CSS Framework Architecture

This document explains the architectural approach of our CSS framework, which leverages CSS cascade layers for a more predictable and maintainable styling system.

## Cascade Layers Overview

Our CSS framework is organized into distinct layers using the `@layer` directive. This creates an explicit cascade order that prevents specificity conflicts and provides a clear mental model for how styles are applied.

Layers are defined in order of increasing specificity:

```css
@layer reset, tokens, engine, theme, palette, defaults, components, utilities, layouts;
```

## Layer Responsibilities

Each layer has a distinct responsibility and role in the cascade:

### 1. Reset Layer
- **Purpose**: Normalize browser defaults with zero specificity
- **Content**: Browser reset styles using `:where()` selectors
- **Specificity**: Zero, allowing easy overrides

### 2. Tokens Layer
- **Purpose**: Define design tokens as CSS variables
- **Content**: Colors, typography, spacing, borders, shadows, etc.
- **Structure**: Raw values without semantic meaning

### 3. Engine Layer
- **Purpose**: Provide color and contrast calculations
- **Content**: Mathematical color transformations and auto-contrast logic
- **Usage**: Powers theme adaptability and accessibility features

### 4. Theme Layer
- **Purpose**: Define semantic color roles and theme variables
- **Content**: Mapping tokens to semantic design roles
- **Features**: Dark mode, high contrast mode, focus states

### 5. Palette Layer
- **Purpose**: Define the complete color palette scales
- **Content**: Color scales for UI elements and data visualization
- **Structure**: Systematic color scales with stepped lightness values

### 6. Defaults Layer
- **Purpose**: Apply default styling to HTML elements
- **Content**: Base typography, form elements, tables, etc.
- **Approach**: Minimal styling with semantic theme variables

### 7. Components Layer
- **Purpose**: Define reusable UI components
- **Content**: Buttons, cards, alerts, navigation, etc.
- **Design**: Self-contained, themable, accessible

### 8. Utilities Layer
- **Purpose**: Provide single-purpose utility classes
- **Content**: Colors, spacing, typography, layout helpers
- **Pattern**: Small, composable classes for rapid development

### 9. Layouts Layer
- **Purpose**: Define layout patterns and structural components
- **Content**: Grid systems, flex layouts, container components
- **Feature**: Container query-based responsive behavior

## File Structure

Each layer is defined in its own file for easier maintenance:

```
src/
├── index.css       # Main entry point defining layers and imports
├── reset.css       # Browser reset styles
├── tokens.css      # Design token definitions
├── engine.css      # Color calculations and functions
├── theme.css       # Semantic color roles and themes
├── palette.css     # Color palette definitions
├── defaults.css    # Default element styling
├── components.css  # Common UI components
├── utilities.css   # Utility classes
└── layouts.css     # Layout patterns and primitives
```

The `index.css` file defines the layer order and imports all other files:

```css
@layer reset, tokens, engine, theme, palette, defaults, components, utilities, layouts;

@import url("reset.css");
@import url("tokens.css");
@import url("engine.css");
@import url("theme.css");
@import url("palette.css");
@import url("defaults.css");
@import url("components.css");
@import url("utilities.css");
@import url("layouts.css");
```

## Cascade Flow

The cascade layers create a deliberate flow of increasing specificity:

1. **Foundation Layers** (reset, tokens, engine)
   - Establish the baseline and design system primitives
   - No visible styles, just the building blocks

2. **System Layers** (theme, palette)
   - Define the visual language and color system
   - Connect tokens to semantic roles

3. **Application Layers** (defaults, components)
   - Apply the visual language to HTML elements and patterns
   - Establish the core look and feel

4. **Override Layers** (utilities, layouts)
   - Provide tools for customization and specific layouts
   - Have the highest specificity for easy application

## Benefits of This Architecture

### 1. Predictable Specificity

- Layer order defeats cascade conflicts, not specificity hacks
- No need for `!important` or complex selectors
- Utilities naturally override components, which override defaults

### 2. Modular Organization

- Each layer has a clear purpose and boundary
- Files can be modified, removed, or replaced independently
- Easier onboarding for new developers

### 3. Performance Optimization

- Individual layers can be loaded or deferred as needed
- Critical CSS can be extracted from foundation layers
- Utilities can be tree-shaken based on usage

### 4. Theming Capability

- Clear separation between tokens and their application
- Themes can be swapped by changing the theme layer
- Design tokens create a single source of truth

## Using This Architecture

### Extending with Custom Styles

When adding custom styles to a project using this framework, you should:

1. Decide which layer is appropriate for your styles
2. Place them in the corresponding layer for proper cascade behavior
3. Use the existing token system and semantic variables

Example:

```css
/* For a custom component */
@layer components {
  .my-custom-component {
    background-color: var(--surface-default);
    color: var(--text-default);
    padding: var(--space-md);
    border-radius: var(--radius-md);
  }
}

/* For a utility class */
@layer utilities {
  .my-custom-utility {
    isolation: isolate;
  }
}
```

### When to Use Each Layer

- **Reset Layer**: Only for global normalization, rarely extended
- **Tokens Layer**: Add new design tokens or variables
- **Engine Layer**: Add new color math or calculated variables
- **Theme Layer**: Add new semantic roles or modes
- **Palette Layer**: Add new color scales or palette extensions
- **Defaults Layer**: Modify default styling of HTML elements
- **Components Layer**: Add new UI components or patterns
- **Utilities Layer**: Add new single-purpose helper classes
- **Layouts Layer**: Add new layout patterns or structures

## Resources

For more information on CSS Cascade Layers:

- [MDN Web Docs: Cascade Layers](https://developer.mozilla.org/en-US/docs/Web/CSS/@layer)
- [CSS Working Group: Cascade Layers Spec](https://www.w3.org/TR/css-cascade-5/#layering)
- [CSS Tricks: A Complete Guide to CSS Cascade Layers](https://css-tricks.com/css-cascade-layers/)


================================================
FILE: docs/introduction.md
================================================
# Introduction

## Philosophy & Core Principles

Our CSS framework is built on a set of fundamental principles designed to provide a robust foundation for modern web development:

### 1. Progressive Enhancement

The framework embraces progressive enhancement, starting with a solid baseline experience that works for all users, then enhancing it for those with more capable browsers. This ensures that your content remains accessible regardless of the user's device or browser capabilities.

### 2. Cascade Layering

We leverage the CSS `@layer` directive to establish a clear and predictable order of specificity. This prevents specificity conflicts and creates a clear mental model of how styles are applied. Each layer has a distinct responsibility, making the codebase easier to maintain and extend.

### 3. Design Token System

At the core of our framework is a comprehensive design token system implemented with CSS custom properties. This creates a single source of truth for design values, enabling consistent interfaces and simplifying theme customization.

### 4. Modern Color Science

Instead of traditional RGB or HSL, we use the OKLCH color space for its perceptual uniformity and improved color manipulation. This enables more predictable color transformations, better contrast ratios, and more accessible interfaces.

### 5. Accessibility First

Accessibility is not an afterthought but a foundational principle. The framework includes enhanced focus states, high contrast mode support, and automatic contrast calculations to ensure your interfaces are usable by everyone.

### 6. Utility-First Approach

While providing sensible defaults and components, the framework embraces a utility-first methodology for rapid development and consistent design implementation. Utility classes are generated from the design token system, ensuring coherence.

### 7. Component Autonomy

Layout components are designed to be self-contained using container queries rather than viewport-based media queries. This enables truly reusable components that adapt to their container rather than the viewport.

## Key Features

### Zero-Specificity Reset

Our reset layer uses the `:where()` pseudo-class to apply browser normalization with zero specificity, preventing specificity issues common in traditional CSS resets.

### Comprehensive Design Token System

The framework includes a complete design token system covering colors, typography, spacing, shadows, animations, and more, all implemented using CSS custom properties.

### Automatic Contrast Calculation

Text colors automatically adjust based on their background to ensure readability, leveraging OKLCH color math for precise contrast control.

### Enhanced High Contrast Mode

Beyond simply respecting `prefers-contrast`, the framework provides specific optimizations for high contrast scenarios, ensuring usability for users with visual impairments.

### Comprehensive Shadow System

A sophisticated shadow system that adapts to dark mode and high contrast preferences, with consistent naming and behavior.

### Enhanced Focus States

Focus states are designed to be clearly visible in all contexts, with support for focus-visible polyfilling and enhanced keyboard navigation.

### Container Query Support

Layout components use container queries for component-level responsive design, enabling truly reusable and context-aware layouts.

## Design Decisions

### Why CSS Layers?

CSS Cascade Layers (`@layer`) provide a way to organize CSS rules into layers with explicit precedence. This solves the traditional problem of CSS specificity conflicts and creates a more maintainable architecture.

### Why OKLCH Colors?

OKLCH (Oklab Lightness-Chroma-Hue) is a perceptually uniform color space that makes color manipulations more predictable. Unlike traditional RGB or HSL, changes in OKLCH values correspond more closely to how humans perceive color differences.

### Why a Utility-First Approach?

Utility classes offer several advantages:
- Direct mapping to design tokens for consistency
- Reduced need for custom CSS
- More predictable styling without side effects
- Improved performance by reducing style recalculations

### Why Container Queries?

Container queries enable responsive designs based on the size of a component's container rather than the viewport. This makes components more reusable and independent of their context.

## Browser Support

The framework is designed for modern browsers, leveraging features like:
- CSS Custom Properties (Variables)
- CSS Grid and Flexbox
- Container Queries
- OKLCH Color Space

For older browsers, we recommend using appropriate polyfills or fallbacks, though the core functionality will work in any browser that supports CSS custom properties.


================================================
FILE: docs/latest-features.md
================================================
Latest and Upcoming CSS Features in 2025
Introduction
Cascading Style Sheets (CSS) is the cornerstone of web presentation, defining the look and feel of websites. As of 2025, CSS is undergoing a significant transformation with new and upcoming features that empower developers to create dynamic, responsive, and maintainable designs. These advancements reduce reliance on JavaScript, enhance performance, and simplify complex styling tasks. This document explores the most impactful CSS features, including CSS Functions and Mixins, Container Queries, View Transitions, and more, with a focus on their practical applications, benefits, and current browser support. Whether you're a seasoned developer or just starting out, these features will help you build modern, user-friendly websites.
Major New Features
1. CSS Functions and Mixins
Description: CSS Functions and Mixins, introduced in the CSS Values and Units Level 5 Module, allow developers to define custom functions and reusable style blocks natively in CSS. This feature mirrors the functionality of preprocessors like SASS, enabling dynamic and reusable styling without external tools.
Benefits:

Reusability: Define style logic once and apply it across multiple elements.
Maintainability: Centralize style definitions for easier updates.
Dynamic Styling: Pass arguments to create flexible, context-aware styles.

Example:
@function adjust-opacity($color, $opacity: 0.5) {
  return rgba($color, $opacity);
}

.element {
  background: adjust-opacity(#ff0000, 0.8);
}

This example defines a function to adjust the opacity of a given color, reducing code repetition.
Browser Support: As of August 2025, this feature is experimental, with partial support in Chromium-based browsers (e.g., Chrome, Edge) behind flags. Broader adoption is expected later in 2025 or 2026. Developers should use polyfills or fallbacks for production environments. W3C: CSS Values and Units Level 5
Use Case: Ideal for design systems where consistent styling across components is crucial, such as applying a brand color with varying opacities.
2. Conditional Styling with if()
Description: The if() function, part of the CSS Values Module Level 5, introduces conditional logic to CSS. It allows styles to be applied based on conditions like element states or custom property values, reducing the need for JavaScript in dynamic styling scenarios.
Benefits:

Context-Aware Designs: Style elements based on dynamic conditions.
Reduced JavaScript Dependency: Handle logic natively in CSS.
Simplified Code: Streamline responsive and state-based styling.

Example:
.element {
  background-color: if(var(--theme) == 'dark', #000, #fff);
}

This sets the background color based on the --theme custom property, switching between black and white.
Browser Support: As of August 2025, if() is in the proposal stage with no native support yet. Developers can simulate similar behavior using custom properties and media queries as fallbacks. W3C: CSS Values and Units Level 5
Use Case: Useful for theming applications, such as switching between light and dark modes without JavaScript.
3. Container Queries
Description: Container Queries, supported by the CSS Containment Module, allow styling based on the size of a parent container rather than the viewport. This enables components to adapt to their context, making them more reusable across different layouts.
Benefits:

Component-Based Styling: Style components based on their container’s size.
Flexibility: Reuse components in various layouts without rewriting media queries.
Simplified Responsive Design: Reduce reliance on global media queries.

Example:
.container {
  container-type: inline-size;
}

@container (min-width: 300px) {
  .card {
    flex-direction: row;
  }
}

This changes the card’s layout to a row when its container is at least 300px wide.
Browser Support: As of August 2025, Container Queries have over 90% global support, with robust adoption in Chrome, Firefox, and Safari. CanIUse: Container Queries
Use Case: Perfect for modular UI components like cards or widgets that need to adapt to different container sizes in dashboards or sidebars.
4. Cascade Layers
Description: Cascade Layers, introduced via the @layer rule, allow developers to organize CSS into layers with defined precedence. This helps manage specificity and prevent style conflicts, especially in large projects or when integrating third-party libraries.
Benefits:

Controlled Specificity: Define which styles take precedence.
Conflict Prevention: Isolate styles for components, themes, or utilities.
Scalability: Ideal for design systems and collaborative teams.

Example:
@layer base {
  body {
    font-family: system-ui, sans-serif;
  }
}

@layer components {
  .button {
    padding: 1rem 2rem;
    color: white;
    background: black;
  }
}

@layer utilities {
  .text-red {
    color: red;
  }
}

@layer base, components, utilities;

This ensures utilities override components, which override base styles, regardless of specificity.
Browser Support: Supported in major browsers with over 95% global support as of August 2025. CanIUse: Cascade Layers
Use Case: Essential for large-scale projects where multiple developers or libraries contribute styles, ensuring predictable cascade behavior.
5. Enhanced attr() Function
Description: The attr() function, redefined in the CSS Values and Units Module Level 5, now works with any CSS property and supports data types like colors and lengths, not just strings. This enables dynamic styling based on HTML attributes.
Benefits:

Dynamic Styling: Use attribute values directly in styles.
Versatility: Apply to properties beyond content.
Fallback Support: Provide default values for robustness.

Example:
div {
  color: attr(data-color color, red);
}

This sets the text color to the data-color attribute value, interpreted as a color, with a fallback to red.
Browser Support: Available in Chrome 133 and later, with expanding support in 2025. Bram.us: CSS attr() Upgrade
Use Case: Useful for theming elements based on data attributes, such as user-customized colors in a CMS-driven site.
6. @property for Custom Properties
Description: The @property rule allows developers to define custom properties with specific types, inheritance behaviors, and initial values. This enhances the power of CSS variables, enabling type safety and animation capabilities.
Benefits:

Type Safety: Ensure properties accept valid values.
Animation Support: Animate custom properties with defined types.
Inheritance Control: Specify whether properties inherit.

Example:
@property --my-color {
  syntax: '<color>';
  inherits: false;
  initial-value: blue;
}

.element {
  background-color: var(--my-color);
}

This defines --my-color as a color property with a default value of blue.
Browser Support: Supported in Chrome 85+, Firefox 128+, Safari 16.4+. MDN: @property
Use Case: Ideal for design systems requiring strict type control, such as animating color transitions in a UI component.
7. @scope for Localized Styling
Description: The @scope rule defines boundaries for CSS rules, preventing style leaks and conflicts. It’s particularly useful in component-based architectures and large projects.
Benefits:

Style Isolation: Limit styles to specific components.
Reduced Conflicts: Avoid unintended style overrides.
Team Collaboration: Simplify styling in shared codebases.

Example:
@scope (.component) {
  p {
    color: blue;
  }
}

This applies the style only to <p> elements within .component.
Browser Support: Supported in Chrome 118, Firefox 128, Safari 17.4+. MDN: @scope
Use Case: Perfect for web components or frameworks like React, where styles need to be scoped to specific modules.
8. Popover API
Description: The Popover API allows developers to create non-modal overlays like tooltips, menus, or hover cards using HTML attributes (popover and popovertarget) or JavaScript. It integrates with CSS for styling and positioning, often using anchor positioning.
Benefits:

Simplified UI Components: Create overlays without complex JavaScript.
Accessibility: Built-in accessibility hints for better user experience.
Flexible Positioning: Use CSS anchor positioning for precise placement.

Example:
<button popovertarget="my-popover">Toggle Popover</button>
<div id="my-popover" popover>
  This is a popover.
</div>
<style>
  #my-popover:popover-open {
    width: 200px;
    position: absolute;
    inset: unset;
    bottom: 5px;
    right: 5px;
  }
</style>

This creates a popover that appears when the button is clicked, styled to appear at the bottom-right.
Browser Support: Supported in Chrome, Safari, and Firefox 125+ as of August 2025. The interesttarget attribute for hover-triggered popovers is experimental in Chrome 139. MDN: Popover API
Use Case: Ideal for tooltips, dropdown menus, or hover cards in interactive UIs, such as profile previews on social media platforms.
9. View Transitions API
Description: The View Transitions API enables smooth animations between different views or states in single-page apps (SPAs) and multi-page apps (MPAs). It uses CSS to define transition behaviors, making page navigation feel more like an in-app experience.
Benefits:

Enhanced User Experience: Create seamless transitions between pages or states.
Minimal JavaScript: Often requires only CSS for MPAs.
Progressive Enhancement: Works gracefully in unsupported browsers.

Example (for MPAs):
@view-transition {
  navigation: auto;
}

::view-transition-old(root) {
  animation: fade-out 0.3s ease;
}

::view-transition-new(root) {
  animation: fade-in 0.3s ease;
}

@keyframes fade-out {
  from { opacity: 1; }
  to { opacity: 0; }
}

@keyframes fade-in {
  from { opacity: 0; }
  to { opacity: 1; }
}

This creates a fade transition between pages.
Browser Support: Supported in Chrome and Safari, with Firefox support expected by late 2025. MDN: View Transition API
Use Case: Enhances navigation in SPAs or MPAs, such as transitioning from a product list to a product detail page.
10. Custom Easing and Spring Animations
Description: CSS supports custom easing through the transition-timing-function and animation-timing-function properties, using functions like cubic-bezier() or linear(). While true spring animations (bouncy, physics-based effects) are not natively supported, developers can approximate them using tools like the CSS Spring Easing Generator, which creates linear() functions to mimic spring behavior.
Benefits:

Natural Animations: Create fluid, organic motion.
Custom Control: Fine-tune animation curves for specific effects.
Tool Support: Generators simplify complex easing calculations.

Example:
.element {
  transition: transform 0.8333s linear(0, 0.0018, 0.0069 1.15%, 0.026 2.3%, 0.0637, 0.1135 5.18%, 0.2229 7.78%, 0.5977 15.84%, 0.7014, 0.7904, 0.8641, 0.9228, 0.9676 28.8%, 1.0032 31.68%, 1.0225, 1.0352 36.29%, 1.0431 38.88%, 1.046 42.05%, 1.0448 44.35%, 1.0407 47.23%, 1.0118 61.63%, 1.0025 69.41%, 0.9981 80.35%, 0.9992 99.94%);
  transform: translateX(100px);
}

This uses a generated linear() function to create a spring-like effect.
Browser Support: Custom easing functions like linear() are supported in Chrome 125, Firefox 118, Safari 15.4+. Spring animations require external tools or JavaScript libraries for full effect. CSS Spring Easing Generator
Use Case: Useful for creating engaging UI animations, such as buttons that bounce when clicked or elements that move with a natural, springy feel.
11. Relative Color Syntax
Description: Relative color syntax, part of the CSS Color Module Level 5, allows colors to be defined relative to another color using the from keyword. This enables easy creation of color variants, such as lighter, darker, or semi-transparent versions.
Benefits:

Dynamic Color Palettes: Create variations from a base color.
Simplified Theming: Adjust colors programmatically.
Maintainability: Centralize color logic in stylesheets.

Example:
:root {
  --base-color: #ff0000;
}

.element {
  background-color: rgb(from var(--base-color) r g b / 0.5);
}

This creates a semi-transparent version of the base color.
Browser Support: Supported in Chrome, Safari, and expanding in Firefox as of August 2025. MDN: Relative Colors
Use Case: Perfect for creating monochromatic color schemes or hover effects that adjust opacity or lightness.
12. OKLCH Color Space
Description: The OKLCH color space, introduced in CSS Color Module Level 4, is a perceptually uniform color model that uses lightness (L), chroma (C), and hue (H). It’s designed to align with human color perception, making it ideal for creating consistent and accessible color palettes.
Benefits:

Perceptual Uniformity: Adjustments in lightness or chroma are visually consistent.
Wide Gamut: Supports Display P3 for vibrant colors.
Accessibility: Easier to ensure readable contrast ratios.

Example:
.element {
  color: oklch(50% 0.15 240);
}

This specifies a color with 50% lightness, 0.15 chroma, and 240-degree hue.
Browser Support: Supported in Chrome, Safari, and Firefox, with over 90% global support as of August 2025. MDN: oklch()
Use Case: Ideal for design systems requiring consistent color variations, such as generating accessible color palettes for buttons or text.
13. Media Query Enhancements
Description: CSS custom properties can now be scoped within media queries, allowing dynamic styling based on viewport conditions. Media Queries Level 5 also introduces features like user preference detection (e.g., prefers-color-scheme).
Benefits:

Dynamic Styling: Adjust styles based on viewport or user preferences.
Simplified Logic: Use variables to streamline responsive design.
User-Centric Design: Adapt to user settings like dark mode.

Example:
:root {
  --main-color: blue;
}

@media (min-width: 600px) {
  :root {
    --main-color: green;
  }
}

body {
  color: var(--main-color);
}

This changes the color based on the viewport width.
Browser Support: CSS variables in media queries are widely supported. Media Queries Level 5 features are in Working Draft, with growing support. MDN: Media Queries
Use Case: Useful for responsive designs that adapt colors or layouts based on screen size or user preferences.
14. Color-Scheme Property
Description: The color-scheme property allows elements to indicate preferred color schemes (e.g., light or dark mode), with user agents adjusting UI elements like scrollbars and form controls accordingly.
Benefits:

User Preference Support: Align with system settings.
Accessibility: Improve readability for users.
Consistency: Ensure UI elements match the chosen scheme.

Example:
:root {
  color-scheme: light dark;
}

This indicates the element supports both light and dark modes.
Browser Support: Well-established since 2022, with near-universal support. MDN: color-scheme
Use Case: Essential for applications that need to adapt to system-wide dark mode settings.
Other Notable Features
1. New Color Functions and Spaces
Description: CSS now supports additional color spaces like LCH, LAB, and HWB, alongside OKLCH, offering better color accuracy and accessibility. The color() function allows specifying colors in specific color spaces.
Benefits:

Improved Contrast: LCH and LAB ensure better readability.
Vibrant Designs: Access to wider color gamuts like Display P3.
Accessibility: Easier to meet contrast requirements.

Browser Support: HWB (94.3%), LCH (92.81%, primarily Safari). LambdaTest: CSS Trends
2. Mathematical Functions: mod(), round()
Description: Functions like mod() and round() enable calculations directly in CSS, useful for dynamic layouts and responsive designs.
Benefits:

Dynamic Values: Calculate sizes and positions on the fly.
Responsive Design: Simplify fluid typography and grids.

Example:
.element {
  width: mod(100px, 20px); /* Returns remainder */
}

Browser Support: Supported in Chrome 125, Firefox 118, Safari 15.4+. MDN: mod
3. Performance Optimizations: content-visibility
Description: The content-visibility property optimizes rendering by controlling when off-screen content is rendered, improving page load times.
Benefits:

Faster Rendering: Skip rendering off-screen elements.
Improved UX: Enhance performance on complex pages.

Example:
.section {
  content-visibility: auto;
}

Browser Support: Supported in Chrome 85, Firefox 125, Safari 18+. MDN: content-visibility
4. CSS Nesting
Description: CSS Nesting allows writing nested rules, improving stylesheet readability and maintainability.
Benefits:

Cleaner Code: Group related styles together.
Maintainability: Easier to manage complex stylesheets.

Example:
.card {
  background: white;
  & .title {
    font-weight: bold;
  }
}

Browser Support: Widely supported in 2025, with over 90% global support. CanIUse: CSS Nesting
5. Viewport Units: svw, lvw, dvw
Description: New viewport units (svw, lvw, dvw) provide precise control over sizing relative to the viewport, accounting for UI elements like scrollbars.
Benefits:

Accurate Sizing: Handle dynamic viewport scenarios.
Responsive Design: Improve layout consistency.

Browser Support: Supported with 97.46% global coverage. LambdaTest: CSS Trends
Upcoming Features to Watch

CSS Shapes Module: Allows text to flow around custom shapes, enhancing layout creativity. Expected to gain traction in 2025.
CSS Font Loading Module: Provides better control over font loading and rendering, improving typography performance.
CSS Grid Layout Module: Continues to evolve with features like subgrid and masonry layouts for precise control.

Conclusion
The CSS landscape in 2025 is vibrant, with features that empower developers to create dynamic, responsive, and efficient web applications. Major advancements like CSS Functions and Mixins, Container Queries, and View Transitions reduce complexity and enhance user experiences, while features like the Popover API, relative color syntax, and OKLCH improve interactivity and color management. As some features are still experimental, developers should test thoroughly and stay updated via resources like the CSS Working Group and MDN. Embracing these tools will help you build modern, user-friendly websites that stand out in the digital world.
Feature Support Table



Feature
Browser Support (August 2025)
Global Support (%)
Key Use Cases



CSS Functions and Mixins
Experimental (Chrome, Edge behind flags)
Partial
Reusable styles, dynamic styling


if() Conditional
Proposal stage, no native support
None
Context-aware designs, reduced JS dependency


Container Queries
Chrome, Firefox, Safari
90+
Responsive components, flexible layouts


Cascade Layers
Chrome, Firefox, Safari
95.08
Specificity management, design systems


Enhanced attr()
Chrome 133+, expanding
Growing
Dynamic attribute-based styling


@property
Chrome 85+, Firefox 128+, Safari 16.4+
90+
Type-safe custom properties, animations


@scope
Chrome 118, Firefox 128, Safari 17.4+
90+
Component isolation, conflict prevention


Popover API
Chrome, Safari, Firefox 125+
90+
Tooltips, menus, hover cards


View Transitions API
Chrome, Safari, Firefox (expected late 2025)
80+
Smooth page/state transitions


Custom Easing/Spring
Chrome 125, Firefox 118, Safari 15.4+ (linear())
96.15
Natural animations, engaging UI


Relative Color Syntax
Chrome, Safari, Firefox (expanding)
80+
Dynamic color palettes, theming


OKLCH Color Space
Chrome, Safari, Firefox
90+
Accessible colors, vibrant designs


Media Query Enhancements
Widely supported (variables), Level 5 growing
95+
Responsive designs, user preferences


color-scheme
All major browsers since 2022
Near-universal
Light/dark mode support, accessibility


Citations

CSS Script: 10 New CSS Features You Should Know
WebTech Tools: New CSS Features in 2025
Medium: 10 CSS New Features to Watch Out for in 2025
DEV Community: CSS Techniques Every Developer Should Know in 2025
LambdaTest: Best 15 CSS Trends to Look Out in 2025
caisy.io: CSS Changes in 2025: What to Expect
MDN: CSS Documentation
Bram.us: CSS attr() Upgrade
CSS-Tricks: Popover and Invoker Articles
W3C: CSS Color Module Level 4
W3C: CSS Color Module Level 5
CSS Spring Easing Generator



================================================
FILE: docs/quick-start.md
================================================
# Quick Start Guide

This guide will help you get started with our CSS framework quickly and efficiently.

## Installation

### Option 1: Use the CDN

The fastest way to get started is to include the framework via CDN:

```html
<link rel="stylesheet" href="https://cdn.example.com/css-framework/index.css">
```

### Option 2: Download the Files

You can download the complete framework or individual layer files from our GitHub repository:

1. Download the entire package from the [releases page](https://github.com/yourusername/css-framework/releases)
2. Extract the files to your project directory
3. Link to the CSS in your HTML

```html
<link rel="stylesheet" href="path/to/css-framework/index.css">
```

### Option 3: Use Individual Layers

If you only need specific features, you can import individual layers:

```html
<!-- Base layers -->
<link rel="stylesheet" href="path/to/css-framework/src/reset.css">
<link rel="stylesheet" href="path/to/css-framework/src/tokens.css">

<!-- Only what you need -->
<link rel="stylesheet" href="path/to/css-framework/src/utilities.css">
<link rel="stylesheet" href="path/to/css-framework/src/layouts.css">
```

## Basic Usage

### HTML Structure

The framework doesn't require any specific HTML structure, but here's a simple template to get started:

```html
<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>My Project</title>
  <link rel="stylesheet" href="path/to/css-framework/index.css">
</head>
<body>
  <header>
    <nav>
      <!-- Navigation content -->
    </nav>
  </header>
  
  <main>
    <!-- Main content -->
  </main>
  
  <footer>
    <!-- Footer content -->
  </footer>
</body>
</html>
```

### Using Utility Classes

Utility classes are the core of the framework. They provide a way to apply styles directly in your HTML:

```html
<div class="bg-surface-default p-md rounded-md shadow-md">
  <h2 class="text-lg font-bold text-default mb-sm">Card Title</h2>
  <p class="text-subtle mb-md">Card description goes here.</p>
  <button class="button button-filled-accent">Action</button>
</div>
```

### Using Layout Components

Layout components provide structured ways to organize content:

```html
<div class="l-grid">
  <div class="bg-surface-subtle p-md rounded-md">Grid Item 1</div>
  <div class="bg-surface-subtle p-md rounded-md">Grid Item 2</div>
  <div class="bg-surface-subtle p-md rounded-md">Grid Item 3</div>
</div>

<div class="l-stack gap-lg">
  <h2>Stack Layout</h2>
  <p>Items stacked vertically with consistent spacing.</p>
  <button>Action</button>
</div>
```

## Dark Mode

The framework automatically supports dark mode based on user preference:

```html
<!-- This will automatically adapt to dark mode -->
<div class="bg-surface-default text-default p-md">
  Content adapts to dark mode automatically
</div>

<!-- Force dark mode regardless of user preference -->
<div class="dark bg-surface-default text-default p-md">
  Always in dark mode
</div>

<!-- Force light mode regardless of user preference -->
<div class="light bg-surface-default text-default p-md">
  Always in light mode
</div>
```

## Common Components

The framework includes several pre-styled components:

### Buttons

```html
<!-- Default button -->
<button class="button">Default Button</button>

<!-- Accent buttons -->
<button class="button button-filled-accent">Filled Accent</button>
<button class="button button-outline-accent">Outline Accent</button>
<button class="button button-text-accent">Text Accent</button>

<!-- Status buttons -->
<button class="button button-filled-success">Success</button>
<button class="button button-filled-warning">Warning</button>
<button class="button button-filled-error">Error</button>
```

### Form Elements

```html
<form class="l-stack gap-md">
  <div>
    <label for="name">Name</label>
    <input type="text" id="name" placeholder="Enter your name">
  </div>
  
  <div>
    <label for="email">Email</label>
    <input type="email" id="email" placeholder="Enter your email">
  </div>
  
  <div>
    <label for="message">Message</label>
    <textarea id="message" rows="4" placeholder="Your message"></textarea>
  </div>
  
  <button type="submit" class="button button-filled-accent">Submit</button>
</form>
```

## Customization

### Overriding CSS Variables

You can customize the framework by overriding CSS variables:

```css
:root {
  /* Customize colors */
  --accent-h: 250;
  --accent-s: 100%;
  --accent-l: 50%;
  
  /* Customize spacing */
  --space-md: 1.5rem;
  
  /* Customize typography */
  --font-family-sans: 'Montserrat', sans-serif;
  --font-size-base: 1.125rem;
}
```

### Creating Custom Components

Compose new components using existing utilities:

```css
.card {
  @apply bg-surface-default p-md rounded-md shadow-md;
}

.card__title {
  @apply text-lg font-bold text-default mb-sm;
}

.card__content {
  @apply text-subtle;
}
```

## Next Steps

- Explore the [Architecture](./architecture.md) to understand the layer system
- Learn about the [Tokens Layer](./layers/tokens.md) to customize design tokens
- Check out the [Utilities Layer](./layers/utilities.md) for all available utility classes
- Discover the [Layouts Layer](./layers/layouts.md) for layout patterns


================================================
FILE: docs/guides/accessibility.md
================================================
# Accessibility Guide

This guide explains the accessibility features of our CSS framework and provides best practices for creating accessible interfaces.

## Core Accessibility Features

### Enhanced Focus States

Our framework includes comprehensive focus state handling:

```css
/* Global focus style for keyboard navigation */
:focus-visible {
  outline: var(--focus-ring-width) var(--focus-ring-style) var(--focus-ring-color);
  outline-offset: var(--focus-ring-offset);
}

/* Custom focus styles for specific elements */
a:focus-visible {
  outline: var(--focus-ring-width) var(--focus-ring-style) var(--focus-ring-color);
  outline-offset: var(--focus-ring-offset);
  text-decoration: none;
}

.button:focus-visible {
  outline: var(--focus-ring-width) var(--focus-ring-style) var(--focus-ring-color);
  outline-offset: var(--focus-ring-offset);
}
```

Key aspects:
- Uses `:focus-visible` to apply focus rings only for keyboard navigation
- Customizable focus ring properties (width, style, color, offset)
- Consistent focus indicators across all interactive elements

### High Contrast Mode Support

The framework automatically adapts to users with high contrast preferences:

```css
@media (prefers-contrast: more) {
  :root {
    /* Increase contrast for text */
    --text-default: oklch(calc(var(--scale-l-12) * var(--contrast-multiplier)) var(--scale-c-2) var(--gray-h));
    --text-muted: oklch(calc(var(--scale-l-8) * var(--contrast-multiplier)) var(--scale-c-3) var(--gray-h));
    
    /* Strengthen border contrast */
    --outline-default: oklch(calc(var(--scale-l-8) * var(--contrast-multiplier)) var(--scale-c-4) var(--gray-h));
    
    /* Make focus indicators more visible */
    --focus-ring-width: 3px;
    --focus-ring-style: dashed;
    --focus-ring-color: var(--outline-focus);
  }
}
```

Additional high contrast features:
- Increased color contrast for all text and UI elements
- More prominent borders for better visual separation
- Enhanced focus indicators with thicker outlines

### Auto-Contrast Text

Our Engine layer includes automatic contrast calculation for text:

```css
--auto-contrast-text: oklch(
  from var(--bg, var(--base))
  clamp(0.1, (var(--l-threshold, 0.65) / l - 1) * 999, 0.98)
  min(c, var(--c-threshold, 0.08))
  h
);
```

This ensures:
- Text always has sufficient contrast against its background
- Adapts automatically to theme changes and color variants
- Reduces chroma (color intensity) for improved readability

### Screen Reader Utilities

The framework includes utilities for screen reader accessibility:

```css
.sr-only {
  position: absolute;
  width: 1px;
  height: 1px;
  padding: 0;
  margin: -1px;
  overflow: hidden;
  clip: rect(0, 0, 0, 0);
  white-space: nowrap;
  border-width: 0;
}

.not-sr-only {
  position: static;
  width: auto;
  height: auto;
  padding: 0;
  margin: 0;
  overflow: visible;
  clip: auto;
  white-space: normal;
}
```

These utilities allow:
- Adding content visible only to screen readers
- Implementing the "visually hidden" pattern properly

### Reduced Motion Support

The framework respects user motion preferences:

```css
@media (prefers-reduced-motion: reduce) {
  :root {
    --animation-duration-fast: 0.01ms;
    --animation-duration-normal: 0.01ms;
    --animation-duration-slow: 0.01ms;
  }
}
```

This ensures:
- Animations and transitions are minimized for users who prefer reduced motion
- Core functionality remains intact without distracting movements

## Accessibility Best Practices

### Text and Typography

1. **Use relative units**
   - Our framework uses `rem` units for font sizes
   - This ensures text scales with user preferences

   ```css
   .text-base { font-size: var(--font-size-base); /* 1rem */ }
   ```

2. **Maintain sufficient line height**
   - Line heights are set to improve readability
   - Minimum recommended line height of 1.5 for body text

   ```css
   body {
     line-height: var(--line-height-normal); /* 1.5 */
   }
   ```

3. **Ensure adequate text spacing**
   - Letter spacing is appropriate for different text sizes
   - Word spacing allows for clear distinction between words

   ```css
   .tracking-wide { letter-spacing: var(--letter-spacing-wide); }
   ```

### Color and Contrast

1. **Meet minimum contrast requirements**
   - Text meets WCAG 2.1 AA requirements (4.5:1 for normal text, 3:1 for large text)
   - Our auto-contrast system helps maintain these ratios

2. **Don't rely on color alone**
   - Always use additional indicators (icons, text, patterns)
   - For example, error states use both color and icons

   ```html
   <div class="alert alert--error">
     <div class="alert__icon">⚠️</div>
     <div class="alert__content">Error message</div>
   </div>
   ```

3. **Test in different color modes**
   - Check interfaces in light mode, dark mode, and high contrast mode
   - Ensure all states are properly visible in each mode

### Interactive Elements

1. **Use semantic HTML**
   - Prefer native elements (`<button>`, `<a>`, etc.) when possible
   - Add appropriate ARIA attributes when extending functionality

   ```html
   <!-- Correct -->
   <button class="button">Click me</button>
   
   <!-- Avoid -->
   <div class="button" onclick="...">Click me</div>
   ```

2. **Ensure proper focus management**
   - All interactive elements must be keyboard accessible
   - Focus order should follow a logical sequence
   - Use `tabindex="0"` only when absolutely necessary

3. **Provide adequate target sizes**
   - Interactive elements have sufficient padding
   - Minimum touch target size of 44×44px for touch interfaces

   ```css
   .button {
     padding: var(--space-button-y, 0.7em) var(--space-button-x, 1.3em);
     /* Ensures adequate touch target */
   }
   ```

### Forms and Inputs

1. **Use explicit labels**
   - Every form control should have an associated label
   - Labels should be properly connected via the `for` attribute

   ```html
   <div class="form-group">
     <label for="name" class="form-label">Name</label>
     <input id="name" class="form-input" type="text">
   </div>
   ```

2. **Provide clear feedback**
   - Error states are visually distinct and described
   - Success states confirm actions were completed

   ```html
   <div class="form-group">
     <label for="email" class="form-label">Email</label>
     <input id="email" class="form-input form-input--invalid" type="email">
     <span class="form-error">Please enter a valid email address</span>
   </div>
   ```

3. **Group related controls**
   - Use fieldsets and legends for related inputs
   - Organize forms in a logical structure

   ```html
   <fieldset>
     <legend>Contact Information</legend>
     <!-- Form controls here -->
   </fieldset>
   ```

### Images and Media

1. **Always use alt text**
   - Provide descriptive alt text for images
   - Use empty alt (`alt=""`) for decorative images

   ```html
   <img src="chart.png" alt="Sales chart showing 20% growth in Q2">
   ```

2. **Consider color blindness**
   - Don't rely solely on color for data visualization
   - Use patterns, shapes, and labels in addition to color

3. **Ensure media controls are accessible**
   - Audio and video players should have keyboard-accessible controls
   - Provide captions and transcripts when applicable

## Testing for Accessibility

### Automated Testing

1. **Use accessibility linters**
   - Integrate tools like axe, WAVE, or Lighthouse
   - Make accessibility testing part of your CI/CD pipeline

2. **Test with browser extensions**
   - Chrome/Edge: Lighthouse, axe DevTools
   - Firefox: WAVE Evaluation Tool

### Manual Testing

1. **Keyboard navigation testing**
   - Navigate your interface using only the keyboard
   - Ensure focus states are clearly visible
   - Check for logical tab order

2. **Screen reader testing**
   - Test with popular screen readers:
     - NVDA or JAWS (Windows)
     - VoiceOver (macOS)
     - TalkBack (Android)
   - Verify that all content is properly announced

3. **Zoom and magnification**
   - Test at 200% zoom
   - Ensure content remains usable and doesn't overlap

4. **User preference testing**
   - Test with different user preferences:
     - Dark mode
     - High contrast mode
     - Reduced motion
     - Increased font size

## ARIA and Semantic HTML

### Using ARIA Appropriately

1. **Use native elements first**
   - Choose semantic HTML elements when possible
   - Only use ARIA when native semantics are insufficient

2. **Common ARIA patterns**
   - Landmarks: `role="navigation"`, `role="main"`, etc.
   - Live regions: `aria-live="polite"`, `aria-live="assertive"`
   - State indicators: `aria-expanded`, `aria-selected`, etc.

   ```html
   <div role="alert" aria-live="assertive" class="alert alert--error">
     An error occurred during form submission
   </div>
   ```

### Semantic Structure

1. **Use proper headings**
   - Maintain a logical heading hierarchy (h1-h6)
   - Don't skip heading levels

   ```html
   <h1>Page Title</h1>
   <section>
     <h2>Section Title</h2>
     <h3>Subsection Title</h3>
   </section>
   ```

2. **Use landmarks appropriately**
   - `<header>`, `<main>`, `<footer>`, `<nav>`, `<aside>`
   - These help screen reader users navigate your page

   ```html
   <header>
     <nav>
       <!-- Navigation items -->
     </nav>
   </header>
   <main>
     <!-- Main content -->
   </main>
   <footer>
     <!-- Footer content -->
   </footer>
   ```

## Implementing Accessible Components

### Modal Dialogs

```html
<div class="modal" role="dialog" aria-labelledby="modal-title" aria-modal="true">
  <div class="modal__dialog">
    <div class="modal__header">
      <h2 id="modal-title" class="modal__title">Modal Title</h2>
      <button class="modal__close" aria-label="Close">×</button>
    </div>
    <div class="modal__body">
      Modal content
    </div>
    <div class="modal__footer">
      <button class="button">Cancel</button>
      <button class="button button--filled-accent">Confirm</button>
    </div>
  </div>
</div>
```

Key accessibility features:
- `role="dialog"` identifies the component as a dialog
- `aria-labelledby` associates the title with the dialog
- `aria-modal="true"` indicates it's a modal dialog
- Focus management (not shown in CSS) should trap focus inside the modal when open

### Tabs

```html
<div class="l-tabs" role="tablist">
  <div class="l-tabs__list">
    <button id="tab1" class="button" role="tab" aria-selected="true" aria-controls="panel1">Tab 1</button>
    <button id="tab2" class="button" role="tab" aria-selected="false" aria-controls="panel2">Tab 2</button>
    <button id="tab3" class="button" role="tab" aria-selected="false" aria-controls="panel3">Tab 3</button>
  </div>
  <div id="panel1" class="l-tabs__panel" role="tabpanel" aria-labelledby="tab1">
    Tab 1 content
  </div>
  <div id="panel2" class="l-tabs__panel" role="tabpanel" aria-labelledby="tab2" hidden>
    Tab 2 content
  </div>
  <div id="panel3" class="l-tabs__panel" role="tabpanel" aria-labelledby="tab3" hidden>
    Tab 3 content
  </div>
</div>
```

Key accessibility features:
- `role="tablist"`, `role="tab"`, and `role="tabpanel"` establish the tabbed interface
- `aria-selected` indicates the currently selected tab
- `aria-controls` associates tabs with their panels
- `aria-labelledby` associates panels with their tabs
- JavaScript (not shown) should handle keyboard navigation between tabs

### Dropdown Menus

```html
<div class="dropdown">
  <button class="button dropdown__trigger" aria-haspopup="true" aria-expanded="false" id="dropdown-menu">
    Menu
  </button>
  <ul class="dropdown__menu" role="menu" aria-labelledby="dropdown-menu">
    <li role="none">
      <a href="#" role="menuitem">Option 1</a>
    </li>
    <li role="none">
      <a href="#" role="menuitem">Option 2</a>
    </li>
    <li role="none">
      <a href="#" role="menuitem">Option 3</a>
    </li>
  </ul>
</div>
```

Key accessibility features:
- `aria-haspopup="true"` indicates the button controls a popup
- `aria-expanded` reflects the open/closed state
- `role="menu"` and `role="menuitem"` establish the menu structure
- `aria-labelledby` associates the menu with its trigger button
- JavaScript (not shown) should handle keyboard navigation within the menu

## Resources

### WCAG Guidelines
- [Web Content Accessibility Guidelines (WCAG) 2.1](https://www.w3.org/TR/WCAG21/)
- [WCAG Quick Reference](https://www.w3.org/WAI/WCAG21/quickref/)

### Testing Tools
- [axe DevTools](https://www.deque.com/axe/)
- [WAVE Evaluation Tool](https://wave.webaim.org/)
- [Lighthouse](https://developers.google.com/web/tools/lighthouse)

### Screen Readers
- [NVDA](https://www.nvaccess.org/) (Windows, free)
- [JAWS](https://www.freedomscientific.com/products/software/jaws/) (Windows, commercial)
- [VoiceOver](https://www.apple.com/accessibility/mac/vision/) (macOS, built-in)
- [TalkBack](https://support.google.com/accessibility/android/answer/6283677) (Android, built-in)

### Additional Resources
- [WAI-ARIA Authoring Practices](https://www.w3.org/WAI/ARIA/apg/)
- [A11y Project Patterns](https://www.a11yproject.com/patterns/)
- [Inclusive Components](https://inclusive-components.design/)


================================================
FILE: docs/guides/color-system.md
================================================
# Color System Guide

This guide explains the color system used in our CSS framework, which leverages the OKLCH color space for more perceptually uniform color manipulation and improved accessibility.

## Core Concepts

Our color system is built around several key concepts:

1. **OKLCH Color Space**: A perceptually uniform color space that provides more intuitive color manipulation
2. **Systematic Scales**: Color scales with consistent perceptual steps in lightness and chroma
3. **Semantic Color Roles**: Mapping of raw color values to their functional purpose in the UI
4. **Calculated Contrast**: Automatic calculation of text colors based on background
5. **Mode Adaptation**: Colors that adapt to dark mode and high contrast mode

## OKLCH Color Space

### What is OKLCH?

OKLCH (Oklab Lightness-Chroma-Hue) is a perceptually uniform color space designed to better match human visual perception:

- **L (Lightness)**: 0-1 value representing perceptual lightness
- **C (Chroma)**: 0+ value representing color intensity (similar to saturation)
- **H (Hue)**: 0-360 degree value representing the color

### Why OKLCH?

OKLCH offers significant advantages over traditional RGB or HSL:

1. **Perceptual Uniformity**: Equal steps in OKLCH values correspond to equal perceived changes in color
2. **Intuitive Control**: Separate control over lightness, chroma, and hue
3. **Wider Gamut**: Access to colors outside sRGB
4. **Better Interpolation**: More natural-looking transitions between colors

### OKLCH in Our Framework

Our framework uses OKLCH for all color definitions:

```css
/* OKLCH color definition */
--accent: oklch(var(--scale-l-6) var(--scale-c-7) var(--primary-h));

/* Using OKLCH for color manipulation */
--accent-lighter: oklch(from var(--accent) calc(l + 0.1) c h);
--accent-darker: oklch(from var(--accent) calc(l - 0.1) c h);
```

## Color Token System

Our framework uses a hierarchical color token system:

### 1. Base Hue Tokens

Base hue values define the foundation of the color system:

```css
/* Base Color Hues */
--primary-h: 220;    /* Primary color hue (blue) */
--success-h: 160;    /* Success color hue (green) */
--warning-h: 35;     /* Warning color hue (amber) */
--error-h: 355;      /* Error color hue (red) */
--info-h: 200;       /* Info color hue (cyan) */
--gray-h: 220;       /* Gray color hue (cool gray) */
--neutral-h: 0;      /* Neutral gray hue (true gray) */
```

### 2. Lightness and Chroma Scales

Systematic scales for lightness and chroma:

```css
/* Lightness Scale (from lightest to darkest) */
--scale-l-0: 0.98;   /* Nearly white */
--scale-l-1: 0.95;
--scale-l-2: 0.90;
/* ... */
--scale-l-11: 0.18;
--scale-l-12: 0.10;  /* Nearly black */

/* Chroma Scale (from least saturated to most saturated) */
--scale-c-1: 0.02;
--scale-c-2: 0.04;
/* ... */
--scale-c-8: 0.16;
--scale-c-9: 0.18;
```

### 3. Color Palette Tokens

Complete color palettes with 13 steps (0-12) for each hue:

```css
/* Accent Color Scale */
--accent-palette-0: oklch(var(--scale-l-0) min(var(--scale-c-1), var(--clamp-max-c-0)) var(--primary-h));
--accent-palette-1: oklch(var(--scale-l-1) min(var(--scale-c-2), var(--clamp-max-c-0)) var(--primary-h));
/* ... through accent-palette-12 */

/* Gray Scale */
--gray-0: oklch(var(--scale-l-0) min(var(--scale-c-1), var(--clamp-max-c-0)) var(--gray-h));
--gray-1: oklch(var(--scale-l-1) min(var(--scale-c-1), var(--clamp-max-c-0)) var(--gray-h));
/* ... through gray-12 */
```

### 4. Semantic Color Tokens

Semantic tokens map palette colors to their functional purpose:

```css
/* Surface Colors */
--base: oklch(var(--scale-l-0) var(--scale-c-1) var(--gray-h));
--surface-default: oklch(var(--scale-l-3) var(--scale-c-2) var(--gray-h));

/* Text Colors */
--text-default: oklch(var(--scale-l-10) var(--scale-c-2) var(--gray-h));
--text-muted: oklch(var(--scale-l-7) var(--scale-c-1) var(--gray-h));

/* Outline Colors */
--outline-default: oklch(var(--scale-l-6) var(--scale-c-2) var(--gray-h));

/* Brand and Feedback Colors */
--accent: oklch(var(--scale-l-6) var(--scale-c-7) var(--primary-h));
--success: oklch(var(--scale-l-5) var(--scale-c-7) var(--success-h));
--error: oklch(var(--scale-l-5) var(--scale-c-7) var(--error-h));
```

## Color Palette Structure

### Scale Steps Design

Each color scale follows a consistent pattern of 13 steps (0-12):

1. **Steps 0-2**: Very light shades (subtle backgrounds, highlights)
2. **Steps 3-5**: Light shades (backgrounds, subtle UI elements)
3. **Steps 6-8**: Mid-range shades (primary UI elements, borders)
4. **Steps 9-11**: Dark shades (text, prominent elements)
5. **Step 12**: Darkest shade (headings, emphasizing text)

### Special Considerations

#### Near-White and Near-Black Colors

We apply special handling for the extremes of the scale:

```css
/* Clamping chroma at the extremes */
--clamp-max-c-0: 0.03;  /* Max chroma for near-whites */
--clamp-max-c-12: 0.04; /* Max chroma for near-blacks */

/* Applied in color definitions */
--gray-0: oklch(var(--scale-l-0) min(var(--scale-c-1), var(--clamp-max-c-0)) var(--gray-h));
```

This prevents "off-white" or overly saturated dark colors.

#### Neutral Grayscale

The framework provides two grayscale options:

1. **Gray Scale**: Slightly tinted grayscale with a cool undertone (default)
2. **Neutral Scale**: True grayscale with zero chroma (pure gray)

## Auto-Contrast Calculation

One of the most powerful features is the automatic contrast calculation:

```css
--auto-contrast-text: oklch(
  from var(--bg, var(--base))
  clamp(0.1, (var(--l-threshold, 0.65) / l - 1) * 999, 0.98)
  min(c, var(--c-threshold, 0.08))
  h
);
```

This formula:
1. Takes the background color as input
2. Calculates an appropriate lightness value that contrasts with the background
3. Constrains the chroma for better readability
4. Maintains the same hue for color harmony

## Color Transformations

The Engine layer provides systematic color transformations:

```css
/* Muted variant - reduced chroma, slightly adjusted lightness */
--color-to-muted: oklch(
  from var(--color-base)
  calc(l * 0.97)
  calc(c * 0.3)
  h
);

/* Subtle variant - higher lightness, much lower chroma */
--color-to-subtle: oklch(
  from var(--color-base)
  calc(l * 1.15)
  calc(c * 0.12)
  h
);

/* Overt variant - slightly lower lightness, higher chroma */
--color-to-overt: oklch(
  from var(--color-base)
  calc(l * 0.85)
  calc(c * 1.2)
  h
);
```

## Dark Mode Color Adaptation

Colors automatically adapt to dark mode:

```css
@media (prefers-color-scheme: dark) {
  :root:not(.light) {
    /* Dark mode adaptations */
    --base: oklch(var(--scale-l-12) var(--scale-c-1) var(--gray-h));
    --text-default: oklch(var(--scale-l-2) var(--scale-c-2) var(--gray-h));
    
    /* Each semantic color is individually adapted for dark mode */
  }
}
```

Instead of simply inverting colors, each semantic role is carefully adjusted.

## High Contrast Mode Adaptation

Colors also adapt to high contrast mode:

```css
@media (prefers-contrast: more) {
  :root {
    /* Increase contrast for better visibility */
    --contrast-multiplier: 1.2;
    --text-default: oklch(calc(var(--scale-l-12) * var(--contrast-multiplier)) var(--scale-c-2) var(--gray-h));
    
    /* Reduce subtle variants in high contrast mode */
    --text-subtle: oklch(calc(var(--scale-l-8) * var(--contrast-multiplier)) var(--scale-c-3) var(--gray-h));
  }
}
```

## Working with the Color System

### Customizing the Color System

To customize the color system, modify the hue variables:

```css
:root {
  --primary-h: 250; /* Purple primary color */
  --secondary-h: 320; /* Pink secondary color */
  --accent-h: var(--primary-h); /* Use primary as accent */
}
```

This will propagate through all related color variables.

### Creating Color Harmonies

The system makes it easy to create color harmonies:

```css
/* Complementary color (opposite on the color wheel) */
--complementary-h: calc(var(--primary-h) + 180);

/* Analogous colors (adjacent on the color wheel) */
--analogous-1-h: calc(var(--primary-h) - 30);
--analogous-2-h: calc(var(--primary-h) + 30);

/* Triadic colors (equidistant on the color wheel) */
--triadic-1-h: var(--primary-h);
--triadic-2-h: calc(var(--primary-h) + 120);
--triadic-3-h: calc(var(--primary-h) + 240);
```

### Generating New Colors

To generate a new color in the same system:

```css
/* Create a new "Rose" color */
--rose-h: 345;

/* Generate a complete rose scale */
--rose-0: oklch(var(--scale-l-0) min(var(--scale-c-1), var(--clamp-max-c-0)) var(--rose-h));
--rose-1: oklch(var(--scale-l-1) min(var(--scale-c-2), var(--clamp-max-c-0)) var(--rose-h));
/* ... and so on */

/* Create semantic variants */
--rose-muted: oklch(var(--scale-l-6) var(--scale-c-3) var(--rose-h));
--rose-subtle: oklch(var(--scale-l-3) var(--scale-c-1) var(--rose-h));
--rose-overt: oklch(var(--scale-l-5) var(--scale-c-8) var(--rose-h));
```

### Using OKLCH in Custom Components

Use OKLCH for color manipulations in custom components:

```css
.custom-component {
  /* Darken a color */
  background-color: oklch(from var(--accent) calc(l - 0.1) c h);
  
  /* Increase saturation */
  border-color: oklch(from var(--accent) l calc(c * 1.5) h);
  
  /* Adjust both lightness and saturation */
  color: oklch(from var(--accent) calc(l - 0.2) calc(c * 0.8) h);
}

/* Hover state with color transformation */
.custom-component:hover {
  background-color: oklch(from var(--accent) calc(l - 0.05) calc(c * 1.2) h);
}
```

## Using Color Utilities

The framework provides comprehensive color utilities:

```html
<!-- Background colors -->
<div class="bg-accent">Accent background</div>
<div class="bg-surface-default">Default surface</div>
<div class="bg-success">Success background</div>

<!-- Text colors -->
<p class="text-default">Default text</p>
<p class="text-subtle">Subtle text</p>
<p class="text-accent">Accent text</p>

<!-- Border colors -->
<div class="border border-outline-default">Default border</div>
<div class="border border-accent">Accent border</div>

<!-- Color palette scales -->
<div class="bg-accent-palette-3">Accent palette light</div>
<div class="bg-accent-palette-6">Accent palette medium</div>
<div class="bg-accent-palette-9">Accent palette dark</div>
```

## Auto-Contrast Text Utilities

The framework includes utilities for auto-contrast text:

```html
<!-- Automatically determines text color based on background -->
<div class="bg-accent text-contrast-on-accent">
  Text with auto contrast on accent background
</div>

<div class="bg-error text-contrast-on-error">
  Text with auto contrast on error background
</div>
```

## Best Practices

1. **Use semantic color variables** rather than direct color values
2. **Test colors in different modes** (light, dark, high contrast)
3. **Check contrast ratios** to ensure WCAG compliance
4. **Use the systematic scales** to maintain design consistency
5. **Leverage auto-contrast calculation** for text over colored backgrounds
6. **Consider color blindness** when designing your color system
7. **Use OKLCH for color manipulation** rather than RGB or HSL
8. **Keep color harmonies consistent** across your design system
9. **Document your color system** for other developers and designers
10. **Test on different screens** as colors can appear differently

## Color Accessibility

To ensure your colors are accessible:

1. **Maintain sufficient contrast ratios**:
   - 4.5:1 for normal text (WCAG AA)
   - 3:1 for large text (WCAG AA)
   - 7:1 for enhanced contrast (WCAG AAA)

2. **Don't rely solely on color** to convey information
   - Always use additional indicators (text, icons, patterns)
   - Our auto-contrast system helps, but isn't enough on its own

3. **Test with color blindness simulators**
   - Protanopia (red-blind)
   - Deuteranopia (green-blind)
   - Tritanopia (blue-blind)

4. **Use the color palette systematically**
   - Follow the scale numbers consistently
   - Use steps 0-2 for backgrounds, 9-12 for text

## Resources

- [OKLCH Color Picker](https://oklch.com/)
- [Color Contrast Checker](https://webaim.org/resources/contrastchecker/)
- [WCAG Color Contrast Guidelines](https://www.w3.org/WAI/WCAG21/Understanding/contrast-minimum.html)
- [Designing for Color Blindness](https://www.toptal.com/designers/colorfilter)
- [MDN OKLCH Documentation](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value/oklch)


================================================
FILE: docs/guides/container-queries.md
================================================
# Container Queries Guide

This guide explains how our CSS framework implements container queries for component-level responsive design, a powerful feature that enables truly reusable and context-aware layouts.

## Core Concepts

Container queries allow you to apply styles based on the size of a containing element rather than the viewport size. This creates a more modular approach to responsive design where components can adapt to their container regardless of where they're placed in the UI.

Our framework leverages container queries throughout its layout system to create:

1. **Self-Contained Components**: Components that adapt to their container size
2. **Context-Aware Layouts**: Layouts that respond to their available space
3. **Reusable Patterns**: Patterns that work in any context, regardless of viewport size
4. **Compositional Design**: The ability to compose complex layouts from adaptable parts

## Container Query Implementation

### Container Types

The framework defines containers using the `container-type` and `container-name` properties:

```css
.l-container {
  container-type: var(--l-container-type, inline-size);
  container-name: var(--l-container-name, layout);
}

.l-grid {
  display: grid;
  container-type: inline-size;
  container-name: layout-grid;
  /* Other grid properties */
}
```

We use different container types depending on the layout needs:
- `inline-size`: Responds to changes in the container's width (most common)
- `size`: Responds to changes in both width and height
- `normal`: A standard container but doesn't establish a query container

### Container Names

Container names help target specific containers in complex nested layouts:

```css
.l-sidebar {
  container-type: inline-size;
  container-name: layout-sidebar;
  /* Other sidebar properties */
}

@container layout-sidebar (min-width: 45em) {
  /* Styles that apply when the sidebar container is at least 45em wide */
}
```

### Container Query Breakpoints

The framework provides standardized container query breakpoints:

```css
:root {
  /* Container Query Breakpoints */
  --cq-bp-xs: 20em;  /* 320px */
  --cq-bp-sm: 30em;  /* 480px */
  --cq-bp-md: 45em;  /* 720px */
  --cq-bp-lg: 60em;  /* 960px */
  --cq-bp-xl: 75em;  /* 1200px */
}

@container layout-grid (min-width: var(--cq-bp-sm)) {
  /* Styles that apply at the small breakpoint */
}

@container layout-grid (min-width: var(--cq-bp-md)) {
  /* Styles that apply at the medium breakpoint */
}
```

## Layout Components with Container Queries

### Grid Layout

The grid layout uses container queries to adjust its columns:

```css
.l-grid {
  display: grid;
  gap: var(--l-grid-gap, var(--space-md));
  grid-template-columns: repeat(auto-fit, minmax(min(100%, var(--l-grid-min-item-size, 15rem)), 1fr));
  container-type: inline-size;
  container-name: layout-grid;
}

@container layout-grid (min-width: var(--cq-bp-md)) {
  .l-grid {
    gap: var(--l-grid-gap-md, var(--space-lg));
  }
}

@container layout-grid (min-width: var(--cq-bp-lg)) {
  .l-grid {
    gap: var(--l-grid-gap-lg, var(--space-xl));
  }
}
```

### Split Layout

The split layout adapts from a stacked to a side-by-side layout:

```css
.l-split {
  display: grid;
  grid-template-columns: 1fr; /* Default to single column */
  gap: var(--l-split-gap, var(--space-lg));
  container-type: inline-size;
  container-name: layout-split;
}

@container layout-split (min-width: var(--l-split-breakpoint, var(--cq-bp-sm))) {
  .l-split {
    grid-template-columns: var(--l-split-fraction, 1fr) 1fr; /* Two columns at breakpoint */
  }
}
```

### Row Layout

The row layout switches between column and row orientations:

```css
.l-row {
  display: flex;
  flex-wrap: var(--l-row-wrap, wrap);
  gap: var(--l-row-gap, var(--space-md));
  container-type: inline-size;
  container-name: layout-row;
  flex-direction: column; /* Default to stacked */
  align-items: var(--l-row-align-stacked, stretch);
}

@container layout-row (min-width: var(--l-row-stack-breakpoint, var(--cq-bp-xs))) {
  .l-row:not(.l-row--force-stack) {
    flex-direction: var(--l-row-direction, row);
    align-items: var(--l-row-align, center);
    justify-content: var(--l-row-justify, flex-start);
  }
}
```

### Sidebar Layout

The sidebar layout adapts its structure based on container width:

```css
.l-sidebar {
  display: grid;
  gap: var(--l-sidebar-gap, var(--space-lg));
  container-type: inline-size;
  container-name: layout-sidebar;
  grid-template-areas: "content" "sidebar"; /* Default stacked layout */
}

.l-sidebar > *:not(.l-sidebar__aside) {
  grid-area: content;
  min-width: 0;
}

.l-sidebar > .l-sidebar__aside {
  grid-area: sidebar;
  min-width: 0;
  width: 100%;
}

@container layout-sidebar (min-width: var(--l-sidebar-breakpoint, var(--cq-bp-md))) {
  .l-sidebar {
    grid-template-columns: var(--l-sidebar-width, minmax(15rem, 25%)) 1fr;
    grid-template-areas: "sidebar content";
  }
  
  .l-sidebar > .l-sidebar__aside {
    width: auto;
  }
  
  .l-sidebar--right {
    grid-template-columns: 1fr var(--l-sidebar-width, minmax(15rem, 25%));
    grid-template-areas: "content sidebar";
  }
}
```

## Using Container Queries

### Basic Usage

To use container queries in your layouts:

1. Define a container with `container-type` and `container-name`:

```html
<div class="l-container">
  <!-- Container content -->
</div>
```

2. Apply container queries in your CSS:

```css
@container layout (min-width: 30em) {
  /* Styles that apply when the container is at least 30em wide */
}
```

### Nested Containers

Containers can be nested for more complex responsive layouts:

```html
<div class="l-container" style="--l-container-name: outer;">
  <div class="l-grid">
    <div class="card">Grid Item 1</div>
    <div class="card">Grid Item 2</div>
  </div>
</div>
```

```css
@container outer (min-width: 60em) {
  .l-grid {
    --l-grid-min-item-size: 20rem;
  }
}

@container layout-grid (min-width: 30em) {
  .card {
    padding: var(--space-lg);
  }
}
```

### Customizing Container Query Breakpoints

You can customize container query breakpoints for specific components:

```html
<div class="l-sidebar" style="--l-sidebar-breakpoint: 50em;">
  <!-- Sidebar that switches layout at 50em instead of the default breakpoint -->
</div>
```

### Progressive Enhancement

For browsers that don't support container queries, the framework provides fallbacks:

1. Default styles that work without container queries
2. Optional non-container-query classes

```html
<!-- Will use container queries if supported -->
<div class="l-row">
  <!-- Content -->
</div>

<!-- Will always use row layout regardless of container support -->
<div class="l-row l-row--no-stack">
  <!-- Content -->
</div>
```

```css
.l-row {
  display: flex;
  flex-direction: column; /* Default for all browsers */
}

@container layout-row (min-width: var(--cq-bp-xs)) {
  .l-row:not(.l-row--force-stack) {
    flex-direction: row; /* Container query enhancement */
  }
}

/* Fallback for browsers without container query support */
.l-row--no-stack {
  flex-direction: row;
}
```

## Creating Container Query Components

### Simple Component Example

Here's how to create a card component that adapts to its container:

```css
.responsive-card {
  container-type: inline-size;
  container-name: card;
  display: flex;
  flex-direction: column;
  padding: var(--space-md);
  border-radius: var(--radius-md);
  background-color: var(--surface-default);
}

.responsive-card__media {
  margin-bottom: var(--space-md);
}

.responsive-card__content {
  flex-grow: 1;
}

@container card (min-width: 24em) {
  .responsive-card {
    flex-direction: row;
    align-items: flex-start;
  }
  
  .responsive-card__media {
    margin-bottom: 0;
    margin-right: var(--space-md);
    width: 40%;
  }
  
  .responsive-card__content {
    width: 60%;
  }
}
```

### Complex Component Example

Here's a more complex product listing component:

```css
.product-listing {
  container-type: inline-size;
  container-name: product;
  display: grid;
  gap: var(--space-md);
  grid-template-areas:
    "image"
    "title"
    "price"
    "description"
    "actions";
}

.product-listing__image { grid-area: image; }
.product-listing__title { grid-area: title; }
.product-listing__price { grid-area: price; }
.product-listing__description { grid-area: description; }
.product-listing__actions { grid-area: actions; }

@container product (min-width: 30em) {
  .product-listing {
    grid-template-columns: 1fr 2fr;
    grid-template-areas:
      "image title"
      "image price"
      "image description"
      "image actions";
  }
}

@container product (min-width: 45em) {
  .product-listing {
    grid-template-columns: 1fr 1fr 1fr;
    grid-template-areas:
      "image title title"
      "image price description"
      "image actions actions";
  }
}
```

## Advanced Techniques

### Container Query Units

Container query units allow you to size elements relative to their container:

```css
.responsive-font {
  /* Font size is 5% of the container width */
  font-size: 5cqi;
}

.responsive-padding {
  /* Padding is 3% of the container width */
  padding: 3cqi;
}
```

Available units:
- `cqw`: 1% of a query container's width
- `cqh`: 1% of a query container's height
- `cqi`: 1% of a query container's inline size
- `cqb`: 1% of a query container's block size
- `cqmin`: The smaller value of `cqi` or `cqb`
- `cqmax`: The larger value of `cqi` or `cqb`

### Style Queries (Future)

While not yet widely supported, style queries will allow querying the style of the container:

```css
@container style(--theme: dark) {
  /* Styles for elements within containers with --theme: dark */
}
```

### Container Query Combinators

Combine container queries for more complex conditions:

```css
@container layout (min-width: 30em) and (max-width: 60em) {
  /* Styles for medium-sized containers */
}

@container layout (min-width: 60em) or (min-height: 40em) {
  /* Styles for wide or tall containers */
}
```

## Best Practices

1. **Start mobile-first**: Define base styles for small containers, then enhance for larger ones
2. **Use standardized breakpoints**: Stick to the defined breakpoints for consistency
3. **Name containers meaningfully**: Use descriptive container names for clarity
4. **Don't over-nest**: Too many nested container queries can be hard to manage
5. **Provide fallbacks**: Ensure layouts work reasonably well even without container query support
6. **Document container behaviors**: Make it clear how components respond to container sizes
7. **Consider both width and height**: Some components may need to respond to container height
8. **Test thoroughly**: Check behavior in a variety of container sizes and contexts
9. **Use container query units sparingly**: They're powerful but can lead to unexpected results
10. **Combine with media queries when appropriate**: Some designs need both approaches

## Browser Support

Container queries are supported in:
- Chrome 105+
- Firefox 110+
- Safari 16+
- Edge 105+

For browsers without support:
- Define sensible defaults
- Consider using feature detection
- Provide fallback classes if needed

```javascript
// Feature detection for container queries
if ('container' in document.documentElement.style || 
    'containerType' in document.documentElement.style) {
  // Container queries are supported
  document.documentElement.classList.add('cq-supported');
} else {
  // Container queries are not supported
  document.documentElement.classList.add('cq-not-supported');
}
```

## Resources

- [MDN Container Queries](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Container_Queries)
- [CSS Working Group: Container Queries Spec](https://drafts.csswg.org/css-contain-3/)
- [Una Kravets: Container Queries for Designers](https://una.im/cqfill/)
- [Ahmad Shadeed: Container Queries in Practice](https://ishadeed.com/article/container-queries-practical-guide/)
- [Every Layout: Layout Primitives](https://every-layout.dev/)


================================================
FILE: docs/guides/customization.md
================================================
# Customization Guide

This guide explains how to customize and extend our CSS framework to meet your specific project needs while maintaining its architectural integrity.

## Core Customization Approaches

There are several ways to customize the framework:

1. **CSS Variables**: Override design tokens to change colors, spacing, typography, etc.
2. **Cascade Layers**: Extend existing layers or add new ones to the cascade
3. **Custom Components**: Create new components that follow the established patterns
4. **Utility Extensions**: Add new utility classes to complement the existing set
5. **Theme Variants**: Create alternative themes or modifications of the default theme

## Customizing with CSS Variables

### Overriding Design Tokens

The simplest way to customize the framework is by overriding CSS variables:

```css
:root {
  /* Override color hues */
  --primary-h: 250; /* Change primary/accent color to purple */
  --success-h: 150; /* Adjust success green */
  
  /* Override spacing scale */
  --space-md: 1.25rem; /* Default is 1rem */
  --space-lg: 2rem;    /* Default is 1.5rem */
  
  /* Override typography */
  --font-family-sans: 'Montserrat', sans-serif;
  --font-size-base: 1.125rem; /* Default is 1rem */
  
  /* Override border radius */
  --radius-md: 8px; /* Default is 6px */
}
```

Place these overrides in your own CSS file and load it after the framework.

### Creating Color Themes

You can create custom color themes:

```css
/* Blue Theme */
.theme-blue {
  --primary-h: 220; /* Blue */
  --secondary-h: 280; /* Purple */
  --tertiary-h: 160; /* Teal */
}

/* Green Theme */
.theme-green {
  --primary-h: 160; /* Green */
  --secondary-h: 220; /* Blue */
  --tertiary-h: 40; /* Gold */
}
```

Apply the theme class to your HTML:

```html
<body class="theme-blue">
  <!-- Blue theme applied -->
</body>
```

### Semantic Variable Overrides

You can customize semantic variables without changing the base tokens:

```css
:root {
  /* Use a different token for a semantic variable */
  --text-default: var(--gray-11); /* Instead of gray-10 */
  --surface-default: var(--gray-1); /* Instead of gray-3 */
  
  /* Create higher contrast between surfaces */
  --surface-subtle: var(--gray-3);
  --surface-muted: var(--gray-2);
}
```

This allows you to change the application of colors without modifying the underlying palette.

## Extending with Cascade Layers

### Adding to Existing Layers

You can extend existing layers with your own styles:

```css
@layer components {
  /* Add a new card variant */
  .card--featured {
    border-left: 4px solid var(--accent);
    background: linear-gradient(
      to right,
      var(--accent-subtle),
      var(--surface-default) 20%
    );
  }
  
  /* Add a new alert variant */
  .alert--feature {
    border-left-color: var(--tertiary);
    background-color: var(--tertiary-subtle);
  }
}

@layer utilities {
  /* Add new utility classes */
  .text-truncate {
    overflow: hidden;
    text-overflow: ellipsis;
    white-space: nowrap;
  }
  
  .aspect-video {
    aspect-ratio: 16 / 9;
  }
}
```

### Adding New Layers

You can add new layers to the cascade:

```css
/* Redefine the cascade order to include your custom layers */
@layer reset, tokens, engine, theme, palette, defaults, components, utilities, layouts, custom-components, overrides;

/* Add your custom layers */
@layer custom-components {
  /* Custom components specific to your project */
  .product-card {
    display: grid;
    grid-template-rows: auto 1fr auto;
    height: 100%;
    /* More styling... */
  }
}

@layer overrides {
  /* Highest specificity overrides for special cases */
  .legacy-component {
    /* Override styles for legacy components */
  }
}
```

## Creating Custom Components

### Component Structure

When creating custom components, follow the established pattern:

```css
@layer components {
  /* Base component */
  .feature-box {
    background-color: var(--surface-default);
    border-radius: var(--radius-lg);
    padding: var(--space-lg);
    box-shadow: var(--shadow-md);
  }
  
  /* Component parts */
  .feature-box__icon {
    color: var(--accent);
    font-size: var(--font-size-2xl);
    margin-bottom: var(--space-sm);
  }
  
  .feature-box__title {
    font-size: var(--font-size-xl);
    font-weight: var(--font-weight-bold);
    color: var(--text-overt);
    margin-bottom: var(--space-xs);
  }
  
  .feature-box__description {
    color: var(--text-default);
  }
  
  /* Component variants */
  .feature-box--compact {
    padding: var(--space-md);
  }
  
  .feature-box--accent {
    background-color: var(--accent-subtle);
    border-left: 4px solid var(--accent);
  }
}
```

### Responsive Components with Container Queries

Create responsive components using container queries:

```css
@layer components {
  .product-card {
    container-type: inline-size;
    container-name: product-card;
    display: grid;
    gap: var(--space-md);
    grid-template-areas:
      "image"
      "content"
      "actions";
  }
  
  .product-card__image {
    grid-area: image;
  }
  
  .product-card__content {
    grid-area: content;
  }
  
  .product-card__actions {
    grid-area: actions;
  }
  
  @container product-card (min-width: 30em) {
    .product-card {
      grid-template-columns: 2fr 3fr;
      grid-template-areas:
        "image content"
        "image actions";
    }
  }
}
```

## Adding Custom Utilities

### Creating Utility Classes

Add your own utility classes to complement the built-in ones:

```css
@layer utilities {
  /* Typography utilities */
  .text-balance { text-wrap: balance; }
  .line-clamp-1 { overflow: hidden; display: -webkit-box; -webkit-box-orient: vertical; -webkit-line-clamp: 1; }
  .line-clamp-2 { overflow: hidden; display: -webkit-box; -webkit-box-orient: vertical; -webkit-line-clamp: 2; }
  .line-clamp-3 { overflow: hidden; display: -webkit-box; -webkit-box-orient: vertical; -webkit-line-clamp: 3; }
  
  /* Animation utilities */
  .animate-fade-in { animation: fade-in var(--animation-duration-normal) var(--ease-out); }
  .animate-slide-up { animation: slide-up var(--animation-duration-normal) var(--ease-out); }
  .animate-pulse { animation: pulse 2s cubic-bezier(0.4, 0, 0.6, 1) infinite; }
  
  /* Transform utilities */
  .scale-hover { transition: transform var(--animation-duration-fast) var(--ease-in-out); }
  .scale-hover:hover { transform: scale(1.05); }
  .rotate-45 { transform: rotate(45deg); }
  .rotate-90 { transform: rotate(90deg); }
  .rotate-180 { transform: rotate(180deg); }
}

@keyframes fade-in {
  from { opacity: 0; }
  to { opacity: 1; }
}

@keyframes slide-up {
  from { transform: translateY(1rem); opacity: 0; }
  to { transform: translateY(0); opacity: 1; }
}

@keyframes pulse {
  0%, 100% { opacity: 1; }
  50% { opacity: 0.5; }
}
```

### Responsive Utilities

Add responsive variants to your utilities:

```css
@layer utilities {
  /* Base utility */
  .hide { display: none; }
  
  /* Responsive variants */
  @media (min-width: 30em) {
    .sm\:hide { display: none; }
    .sm\:show { display: block; }
  }
  
  @media (min-width: 48em) {
    .md\:hide { display: none; }
    .md\:show { display: block; }
  }
  
  @media (min-width: 64em) {
    .lg\:hide { display: none; }
    .lg\:show { display: block; }
  }
}
```

## Creating Theme Variants

### Complete Theme System

You can create a comprehensive theme system:

```css
/* Define the theme variables in the theme layer */
@layer theme {
  /* Default (light) theme */
  :root {
    --base: oklch(var(--scale-l-0) var(--scale-c-1) var(--gray-h));
    --text-default: oklch(var(--scale-l-10) var(--scale-c-2) var(--gray-h));
    /* Other default theme variables */
  }
  
  /* Dark theme */
  .dark, :root.dark, @media (prefers-color-scheme: dark) {
    :root:not(.light) {
      --base: oklch(var(--scale-l-12) var(--scale-c-1) var(--gray-h));
      --text-default: oklch(var(--scale-l-2) var(--scale-c-2) var(--gray-h));
      /* Other dark theme variables */
    }
  }
  
  /* High contrast theme */
  .high-contrast, @media (prefers-contrast: more) {
    --contrast-multiplier: 1.2;
    --text-default: oklch(calc(var(--scale-l-12) * var(--contrast-multiplier)) var(--scale-c-2) var(--gray-h));
    /* Other high contrast theme variables */
  }
  
  /* Specific branded themes */
  .theme-blue {
    --primary-h: 220;
    --accent: oklch(var(--scale-l-6) var(--scale-c-7) var(--primary-h));
    /* Other theme customizations */
  }
  
  .theme-green {
    --primary-h: 150;
    --accent: oklch(var(--scale-l-6) var(--scale-c-7) var(--primary-h));
    /* Other theme customizations */
  }
}
```

### Theme Switching

Implement theme switching with JavaScript:

```javascript
// Theme toggle function
function setTheme(themeName) {
  // Remove all theme classes
  document.documentElement.classList.remove(
    'light', 'dark', 'high-contrast', 'theme-blue', 'theme-green'
  );
  
  // Add the selected theme class
  if (themeName !== 'default') {
    document.documentElement.classList.add(themeName);
  }
  
  // Store the preference
  localStorage.setItem('theme', themeName);
}

// Initialize theme on page load
function initTheme() {
  const storedTheme = localStorage.getItem('theme');
  
  if (storedTheme) {
    setTheme(storedTheme);
  } else {
    // Detect system preferences
    if (window.matchMedia('(prefers-color-scheme: dark)').matches) {
      setTheme('dark');
    }
  }
}

// Listen for system preference changes
window.matchMedia('(prefers-color-scheme: dark)').addEventListener('change', (e) => {
  if (!localStorage.getItem('theme')) {
    setTheme(e.matches ? 'dark' : 'default');
  }
});

// Initialize on page load
document.addEventListener('DOMContentLoaded', initTheme);
```

## Advanced Customization Techniques

### Custom Color System

To completely customize the color system:

```css
@layer tokens {
  :root {
    /* Define custom color hues */
    --brand-blue-h: 210;
    --brand-green-h: 160;
    --brand-purple-h: 270;
    
    /* Define custom lightness and chroma scales */
    --brand-l-scale-0: 0.97;
    --brand-l-scale-1: 0.92;
    /* ... other scale values */
    
    --brand-c-scale-0: 0.03;
    --brand-c-scale-1: 0.06;
    /* ... other scale values */
  }
}

@layer palette {
  :root {
    /* Create your custom color palette */
    --brand-blue-1: oklch(var(--brand-l-scale-0) var(--brand-c-scale-0) var(--brand-blue-h));
    --brand-blue-2: oklch(var(--brand-l-scale-1) var(--brand-c-scale-1) var(--brand-blue-h));
    /* ... other palette colors */
  }
}

@layer theme {
  :root {
    /* Map your custom colors to semantic roles */
    --brand-primary: var(--brand-blue-5);
    --brand-secondary: var(--brand-purple-5);
    --brand-accent: var(--brand-green-5);
    
    /* Override the framework's semantic colors with your brand colors */
    --accent: var(--brand-primary);
    --secondary: var(--brand-secondary);
    --tertiary: var(--brand-accent);
  }
}
```

### Custom Typography Scale

To implement a custom typography scale:

```css
@layer tokens {
  :root {
    /* Define a custom modular scale */
    --type-scale-ratio: 1.2; /* Minor third */
    --font-size-base: 1rem;
    --font-size-xs: calc(var(--font-size-base) / var(--type-scale-ratio) / var(--type-scale-ratio));
    --font-size-sm: calc(var(--font-size-base) / var(--type-scale-ratio));
    --font-size-md: calc(var(--font-size-base) * var(--type-scale-ratio));
    --font-size-lg: calc(var(--font-size-base) * var(--type-scale-ratio) * var(--type-scale-ratio));
    --font-size-xl: calc(var(--font-size-base) * var(--type-scale-ratio) * var(--type-scale-ratio) * var(--type-scale-ratio));
    --font-size-2xl: calc(var(--font-size-base) * var(--type-scale-ratio) * var(--type-scale-ratio) * var(--type-scale-ratio) * var(--type-scale-ratio));
    
    /* Custom font stacks */
    --font-family-sans: 'Roboto', -apple-system, BlinkMacSystemFont, sans-serif;
    --font-family-serif: 'Merriweather', Georgia, serif;
    --font-family-mono: 'Fira Code', monospace;
    
    /* Custom line heights */
    --line-height-tight: 1.2;
    --line-height-normal: 1.6;
    --line-height-relaxed: 1.8;
  }
}
```

### Custom Spacing Scale

To create a custom spacing scale:

```css
@layer tokens {
  :root {
    /* Define a custom spacing scale based on the golden ratio */
    --space-ratio: 1.618; /* Golden ratio */
    --space-base: 1rem;
    --space-3xs: calc(var(--space-base) / var(--space-ratio) / var(--space-ratio) / var(--space-ratio));
    --space-2xs: calc(var(--space-base) / var(--space-ratio) / var(--space-ratio));
    --space-xs: calc(var(--space-base) / var(--space-ratio));
    --space-sm: var(--space-base);
    --space-md: calc(var(--space-base) * var(--space-ratio));
    --space-lg: calc(var(--space-base) * var(--space-ratio) * var(--space-ratio));
    --space-xl: calc(var(--space-base) * var(--space-ratio) * var(--space-ratio) * var(--space-ratio));
    --space-2xl: calc(var(--space-base) * var(--space-ratio) * var(--space-ratio) * var(--space-ratio) * var(--space-ratio));
    --space-3xl: calc(var(--space-base) * var(--space-ratio) * var(--space-ratio) * var(--space-ratio) * var(--space-ratio) * var(--space-ratio));
  }
}
```

## Best Practices

1. **Respect the Layer System**: Add your customizations to the appropriate cascade layer
2. **Use CSS Variables**: Modify design tokens rather than overriding component styles directly
3. **Follow Naming Conventions**: Maintain consistent naming patterns for your custom additions
4. **Document Your Customizations**: Keep track of your modifications for future reference
5. **Test Across Themes**: Ensure your customizations work in light mode, dark mode, and high contrast mode
6. **Avoid !important**: Let the cascade layers handle specificity instead
7. **Be Mindful of Performance**: Don't add unnecessary styles or complex selectors
8. **Maintain Accessibility**: Ensure your customizations meet accessibility standards
9. **Create Reusable Patterns**: Design custom components and utilities to be reusable
10. **Stay DRY**: Don't repeat styles that could be handled by existing utilities

## Handling Updates

When updating the framework, consider these approaches:

1. **Use Version Control**: Track your customizations separately from the framework
2. **Isolate Customizations**: Keep all your custom styles in separate files
3. **Document Dependencies**: Note which framework features your customizations depend on
4. **Test Thoroughly**: After updating, test your customizations to ensure they still work
5. **Use Feature Detection**: For browser features, use feature detection rather than hard-coding support

## Resources

- [MDN: Using CSS custom properties (variables)](https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_custom_properties)
- [MDN: Cascade layers (@layer)](https://developer.mozilla.org/en-US/docs/Web/CSS/@layer)
- [CSS Working Group: CSS Custom Properties](https://www.w3.org/TR/css-variables-1/)
- [CSS Working Group: CSS Cascade 5](https://www.w3.org/TR/css-cascade-5/)
- [CSS Tricks: A Complete Guide to Custom Properties](https://css-tricks.com/a-complete-guide-to-custom-properties/)


================================================
FILE: docs/guides/dark-mode.md
================================================
# Dark Mode Guide

This guide explains how our CSS framework implements dark mode and how to work with it effectively in your projects.

## Core Concepts

Our framework includes built-in dark mode support using:

1. **CSS Variables**: Theme colors are defined as variables that change in dark mode
2. **Media Queries**: Automatic detection of user preference via `prefers-color-scheme`
3. **Class Toggle**: Manual control through `.dark` and `.light` classes
4. **Color Space**: OKLCH color space for perceptually uniform color transformations

## Automatic Dark Mode

The framework automatically detects the user's preferred color scheme:

```css
@media (prefers-color-scheme: dark) {
  :root:not(.light) {
    /* Dark mode color variables */
    --base: oklch(var(--scale-l-12) var(--scale-c-1) var(--gray-h));
    --bedrock: oklch(var(--scale-l-11) var(--scale-c-2) var(--gray-h));
    --surface-muted: oklch(var(--scale-l-11) var(--scale-c-1) var(--gray-h));
    --surface-subtle: oklch(var(--scale-l-10) var(--scale-c-1) var(--gray-h));
    --surface-default: oklch(var(--scale-l-9) var(--scale-c-2) var(--gray-h));
    --surface-overt: oklch(var(--scale-l-8) var(--scale-c-2) var(--gray-h));
    
    /* Dark mode text colors */
    --text-muted: oklch(var(--scale-l-5) var(--scale-c-1) var(--gray-h));
    --text-subtle: oklch(var(--scale-l-4) var(--scale-c-2) var(--gray-h));
    --text-default: oklch(var(--scale-l-2) var(--scale-c-2) var(--gray-h));
    --text-overt: oklch(var(--scale-l-0) var(--scale-c-1) var(--gray-h));
    
    /* Dark mode outline colors */
    --outline-muted: oklch(var(--scale-l-8) var(--scale-c-1) var(--gray-h));
    --outline-subtle: oklch(var(--scale-l-7) var(--scale-c-2) var(--gray-h));
    --outline-default: oklch(var(--scale-l-6) var(--scale-c-2) var(--gray-h));
    --outline-overt: oklch(var(--scale-l-5) var(--scale-c-3) var(--gray-h));
    
    /* Dark mode shadow color */
    --shadow-color-base: 220 30% 80%;
    
    /* Other dark mode adaptations... */
  }
}
```

The `:not(.light)` selector ensures that dark mode is only applied when the user hasn't explicitly chosen light mode.

## Manual Dark Mode Control

You can manually control dark mode using CSS classes:

```html
<!-- Force dark mode regardless of system preference -->
<div class="dark">
  This content will always use dark mode
</div>

<!-- Force light mode regardless of system preference -->
<div class="light">
  This content will always use light mode
</div>
```

These classes can be applied to any element, including the `<html>` or `<body>` tag to control the entire page:

```html
<html class="dark">
  <!-- Entire page in dark mode -->
</html>
```

## Dark Mode Implementation Details

### Color Inversion Philosophy

Our dark mode doesn't simply invert colors or swap fixed values. Instead, it:

1. Inverts the lightness scale (light colors become dark, dark colors become light)
2. Slightly reduces chroma (color intensity) for better visual comfort
3. Maintains the same hues for color harmony and consistency

### Shadow Adjustments

Shadows work differently in dark mode:

```css
/* Light mode shadow base */
--shadow-color-base: 220 10% 10%;

/* Dark mode shadow base */
--shadow-color-base: 220 30% 80%;
```

In dark mode:
- Shadow colors are lighter rather than darker
- Opacity is adjusted for better visibility
- Spread and blur may be increased slightly

### Focus State Adaptation

Focus states are adapted for better visibility in dark mode:

```css
/* Dark mode focus adjustments */
--focus-ring-color: oklch(var(--scale-l-3) var(--scale-c-8) var(--primary-h));
--focus-ring-offset: 3px;
```

## Working with Dark Mode

### Testing Dark Mode

To effectively test dark mode:

1. **Browser Tools**: Use browser developer tools to toggle dark mode
   - Chrome: DevTools > Rendering > Emulate CSS prefers-color-scheme: dark
   - Firefox: DevTools > 3-dot menu > Settings > Enable dark mode

2. **Manual Toggle**: Add a theme toggle to your application
   ```html
   <button onclick="document.documentElement.classList.toggle('dark')">
     Toggle Dark Mode
   </button>
   ```

3. **System Preference**: Change your operating system's theme setting

### Creating Dark Mode Compatible Components

When building custom components:

1. **Use semantic variables** instead of hard-coded colors
   ```css
   /* Good */
   .custom-component {
     background-color: var(--surface-default);
     color: var(--text-default);
   }
   
   /* Avoid */
   .custom-component {
     background-color: white;
     color: black;
   }
   ```

2. **Adjust shadows appropriately**
   ```css
   .custom-card {
     box-shadow: var(--shadow-md);
     /* Shadow automatically adapts to dark mode */
   }
   ```

3. **Consider contrast for all states**
   ```css
   .custom-button:hover {
     background-color: var(--highlight-bg-subtle);
     /* Uses a variable that adjusts properly in dark mode */
   }
   ```

### Dark Mode Specific Overrides

For cases where you need dark-mode-specific styles:

```css
/* Component with dark mode override */
.special-component {
  background-image: url('light-image.jpg');
}

@media (prefers-color-scheme: dark) {
  :root:not(.light) .special-component {
    background-image: url('dark-image.jpg');
  }
}

/* Or with class-based approach */
.dark .special-component {
  background-image: url('dark-image.jpg');
}
```

### Images and Media in Dark Mode

For images and media that need to adapt to dark mode:

1. **Use SVG with currentColor**
   ```html
   <svg fill="currentColor">
     <!-- SVG will inherit text color which adapts to dark mode -->
   </svg>
   ```

2. **Use the `<picture>` element with `prefers-color-scheme`**
   ```html
   <picture>
     <source srcset="dark-image.jpg" media="(prefers-color-scheme: dark)">
     <img src="light-image.jpg" alt="Description">
   </picture>
   ```

3. **Apply filters to invert images**
   ```css
   @media (prefers-color-scheme: dark) {
     .invertible-image {
       filter: invert(1) hue-rotate(180deg);
     }
   }
   ```

## Implementing a Theme Toggle

### Basic Toggle Implementation

Here's a simple JavaScript implementation for a theme toggle:

```javascript
// Theme toggle function
function toggleTheme() {
  // Check if user has a preference stored
  const currentTheme = localStorage.getItem('theme');
  
  if (currentTheme === 'dark') {
    document.documentElement.classList.remove('dark');
    document.documentElement.classList.add('light');
    localStorage.setItem('theme', 'light');
  } else {
    document.documentElement.classList.remove('light');
    document.documentElement.classList.add('dark');
    localStorage.setItem('theme', 'dark');
  }
}

// Initialize theme on page load
function initTheme() {
  // Check if user has a preference stored
  const storedTheme = localStorage.getItem('theme');
  
  if (storedTheme === 'dark') {
    document.documentElement.classList.add('dark');
  } else if (storedTheme === 'light') {
    document.documentElement.classList.add('light');
  } else {
    // If no preference stored, check system preference
    if (window.matchMedia('(prefers-color-scheme: dark)').matches) {
      document.documentElement.classList.add('dark');
    }
  }
}

// Initialize on page load
document.addEventListener('DOMContentLoaded', initTheme);

// Listen for system preference changes
window.matchMedia('(prefers-color-scheme: dark)').addEventListener('change', (e) => {
  if (!localStorage.getItem('theme')) {
    if (e.matches) {
      document.documentElement.classList.add('dark');
      document.documentElement.classList.remove('light');
    } else {
      document.documentElement.classList.add('light');
      document.documentElement.classList.remove('dark');
    }
  }
});
```

### Toggle Button HTML

```html
<button class="theme-toggle" onclick="toggleTheme()" aria-label="Toggle dark mode">
  <span class="theme-toggle__icon theme-toggle__icon--light">☀️</span>
  <span class="theme-toggle__icon theme-toggle__icon--dark">🌙</span>
</button>
```

### Toggle Button CSS

```css
.theme-toggle {
  background: none;
  border: none;
  cursor: pointer;
  padding: 0.5rem;
  border-radius: var(--radius-full);
  color: var(--text-default);
}

.theme-toggle:hover {
  background-color: var(--surface-subtle);
}

.theme-toggle__icon--dark {
  display: none;
}

.theme-toggle__icon--light {
  display: inline;
}

.dark .theme-toggle__icon--dark {
  display: inline;
}

.dark .theme-toggle__icon--light {
  display: none;
}
```

## Advanced Dark Mode Topics

### Color Theory in Dark Mode

When designing for dark mode, consider these principles:

1. **Reduce saturation**: Colors appear more vibrant on dark backgrounds, so reduce saturation
2. **Increase contrast carefully**: Too much contrast can cause eye strain
3. **Avoid pure black**: Use dark grays instead of pure black for better readability
4. **Reduce blue light**: Consider slightly warming dark backgrounds

Our framework handles these automatically through the OKLCH color adjustments.

### Handling User Preferences and Defaults

When implementing dark mode, consider these scenarios:

1. **System preference**: Respect the user's system preference initially
2. **User override**: Allow users to override the system preference
3. **Per-page preference**: Consider whether theme should be remembered globally or per page
4. **Time-based switching**: Consider automatically switching based on time of day

### Transition Effects

To create a smooth transition between light and dark modes:

```css
:root {
  --base: oklch(var(--scale-l-0) var(--scale-c-1) var(--gray-h));
  /* Other light mode variables... */
  
  transition: color 0.3s ease, background-color 0.3s ease, border-color 0.3s ease, outline-color 0.3s ease;
}

@media (prefers-color-scheme: dark) {
  :root:not(.light) {
    --base: oklch(var(--scale-l-12) var(--scale-c-1) var(--gray-h));
    /* Other dark mode variables... */
  }
}

/* Or for class-based approach */
.dark {
  --base: oklch(var(--scale-l-12) var(--scale-c-1) var(--gray-h));
  /* Other dark mode variables... */
}

/* Disable transitions for users who prefer reduced motion */
@media (prefers-reduced-motion: reduce) {
  :root {
    transition: none;
  }
}
```

## Performance and Optimization

### Reducing Flash of Incorrect Theme

To prevent a flash of incorrect theme (FOIT), you can use:

1. **Early theme detection**:
   ```html
   <script>
     // Inline script in the <head> to set theme before page renders
     const theme = localStorage.getItem('theme') || 
                  (window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light');
     document.documentElement.classList.add(theme);
   </script>
   ```

2. **CSS-only approach** (no stored preference):
   ```html
   <style>
     @media (prefers-color-scheme: dark) {
       :root:not(.light) {
         /* Critical dark mode variables */
         --base: #121212;
         --text-default: #e0e0e0;
       }
     }
   </style>
   ```

### Minimize Repaints

Dark mode can cause performance issues if not implemented carefully:

1. **Only transition necessary properties**:
   ```css
   /* Better performance */
   :root {
     transition: color 0.3s ease, background-color 0.3s ease;
   }
   
   /* Avoid */
   :root {
     transition: all 0.3s ease;
   }
   ```

2. **Use hardware-accelerated properties**:
   ```css
   /* Use transform and opacity for transitions where possible */
   .card {
     transition: transform 0.3s ease, opacity 0.3s ease;
   }
   ```

## Best Practices

1. **Use semantic color variables** rather than direct color values
2. **Test both modes thoroughly** for contrast and readability
3. **Respect user preferences** by checking `prefers-color-scheme`
4. **Allow manual override** through a theme toggle
5. **Ensure smooth transitions** between modes when switching
6. **Consider accessibility** in both light and dark modes
7. **Test with actual users** to ensure your dark mode is comfortable
8. **Provide context-appropriate imagery** for each mode
9. **Use CSS custom properties** for dynamic theme switching
10. **Keep color systems consistent** between modes


================================================
FILE: docs/guides/high-contrast.md
================================================
# High Contrast Mode Guide

This guide explains how our CSS framework supports high contrast mode, an important accessibility feature that helps users with low vision or visual impairments.

## Core Concepts

High contrast mode is designed to improve readability by:

1. **Increasing color contrast** between foreground and background elements
2. **Simplifying color palettes** to reduce visual complexity
3. **Emphasizing borders and outlines** to better delineate UI elements
4. **Removing subtle visual effects** that may reduce visibility

Our framework supports high contrast mode through:
- Media query detection via `prefers-contrast`
- Increased contrast token adjustments
- Enhanced focus states and borders
- Removed or simplified background patterns and gradients

## Automatic High Contrast Detection

The framework automatically detects when a user prefers high contrast:

```css
@media (prefers-contrast: more) {
  :root {
    /* High contrast mode variables */
    --contrast-multiplier: 1.2;
    
    /* Increase text contrast */
    --text-default: oklch(calc(var(--scale-l-12) * var(--contrast-multiplier)) var(--scale-c-2) var(--gray-h));
    --text-muted: oklch(calc(var(--scale-l-8) * var(--contrast-multiplier)) var(--scale-c-3) var(--gray-h));
    
    /* Increase border contrast */
    --outline-default: oklch(calc(var(--scale-l-8) * var(--contrast-multiplier)) var(--scale-c-4) var(--gray-h));
    --outline-subtle: oklch(calc(var(--scale-l-7) * var(--contrast-multiplier)) var(--scale-c-3) var(--gray-h));
    
    /* Strengthen focus indicators */
    --focus-ring-width: 3px;
    --focus-ring-style: dashed;
    --focus-ring-color: var(--outline-focus);
    
    /* Increase shadow contrast */
    --shadow-color-base: 220 35% 10%;
    
    /* Other high contrast adaptations... */
  }
}
```

## High Contrast Implementation Details

### Color Contrast Enhancement

In high contrast mode, we make several key adjustments to colors:

1. **Increased lightness differential** between text and backgrounds
2. **Slightly increased chroma** (color intensity) for better differentiation
3. **Simplified color palettes** to focus on core visual distinctions
4. **Bolder borders** around interactive elements

### Focus State Enhancement

Focus states are significantly enhanced in high contrast mode:

```css
@media (prefers-contrast: more) {
  :root {
    /* Enhanced focus states */
    --focus-ring-width: 3px;
    --focus-ring-style: dashed;
    --focus-ring-offset: 3px;
  }
  
  /* Add outlines to additional elements */
  button:focus-visible, 
  a:focus-visible, 
  input:focus-visible, 
  select:focus-visible, 
  textarea:focus-visible {
    outline: var(--focus-ring-width) var(--focus-ring-style) var(--focus-ring-color);
    outline-offset: var(--focus-ring-offset);
  }
}
```

### Border and Outline Enhancements

In high contrast mode, borders and outlines are enhanced:

```css
@media (prefers-contrast: more) {
  /* Add borders to elements that might not have them normally */
  .card, .alert, .badge {
    border: 2px solid var(--outline-default);
  }
  
  /* Ensure all inputs have visible borders */
  input, select, textarea {
    border-width: 2px;
  }
  
  /* Add borders to interactive elements */
  button, .button, a.nav__link, summary {
    outline: 1px solid currentColor;
    outline-offset: -1px;
  }
}
```

### Pattern and Background Simplification

In high contrast mode, we simplify backgrounds and patterns:

```css
@media (prefers-contrast: more) {
  /* Remove subtle background patterns */
  .pattern-bg {
    background-image: none;
  }
  
  /* Increase contrast of alternating rows */
  tr:nth-child(even) {
    background-color: var(--surface-overt);
  }
  
  /* Simplify gradient backgrounds */
  .gradient-bg {
    background-image: none;
    background-color: var(--surface-default);
  }
}
```

## Working with High Contrast Mode

### Testing High Contrast Mode

To effectively test high contrast mode:

1. **Browser Support**: 
   - Currently, the `prefers-contrast` media feature is supported in Firefox and Safari
   - For browsers without support, simulate it by adding a `.high-contrast` class

2. **System Settings**:
   - Windows: Settings > Ease of Access > High Contrast
   - macOS: System Preferences > Accessibility > Display > Increase Contrast

3. **Manual Testing**:
   - Add a class to force high contrast mode regardless of system preference
   ```html
   <div class="high-contrast">
     <!-- Content with forced high contrast mode -->
   </div>
   ```

### Design Considerations for High Contrast

When designing with high contrast in mind:

1. **Avoid relying solely on color** to convey information
2. **Use strong borders** around interactive elements
3. **Ensure sufficient spacing** between elements
4. **Test text on various backgrounds** to ensure readability
5. **Consider text size and font weight** for improved readability

### High Contrast Compatible Components

When building custom components:

1. **Use semantic variables** that will adapt to high contrast mode
   ```css
   /* Good */
   .custom-component {
     border-color: var(--outline-default);
   }
   
   /* Avoid */
   .custom-component {
     border-color: rgba(0, 0, 0, 0.1);
   }
   ```

2. **Consider interaction states**
   ```css
   .custom-button:hover {
     background-color: var(--highlight-bg-subtle);
     /* Uses a variable that adjusts properly in high contrast mode */
   }
   ```

3. **Don't rely on subtle differences**
   ```css
   /* Better for high contrast mode */
   .status-indicator {
     color: var(--text-default);
     border: 2px solid currentColor;
   }
   
   /* Instead of */
   .status-indicator {
     color: var(--text-subtle);
     background-color: var(--surface-subtle);
   }
   ```

### High Contrast Specific Overrides

For cases where you need high-contrast-specific styles:

```css
/* Component with high contrast override */
.subtle-card {
  box-shadow: var(--shadow-sm);
  border: 1px solid transparent;
}

@media (prefers-contrast: more) {
  .subtle-card {
    box-shadow: none;
    border: 2px solid var(--outline-default);
  }
}
```

## Implementing a High Contrast Toggle

While high contrast mode should primarily respect system settings, you can offer a manual toggle for testing or user preference:

```javascript
// High contrast toggle function
function toggleHighContrast() {
  document.documentElement.classList.toggle('high-contrast');
  localStorage.setItem('highContrast', document.documentElement.classList.contains('high-contrast'));
}

// Initialize high contrast setting on page load
function initHighContrast() {
  const storedPreference = localStorage.getItem('highContrast');
  
  if (storedPreference === 'true') {
    document.documentElement.classList.add('high-contrast');
  }
}

// Initialize on page load
document.addEventListener('DOMContentLoaded', initHighContrast);
```

```css
/* CSS for high contrast class */
.high-contrast {
  --contrast-multiplier: 1.2;
  --text-default: oklch(calc(var(--scale-l-12) * var(--contrast-multiplier)) var(--scale-c-2) var(--gray-h));
  --text-muted: oklch(calc(var(--scale-l-8) * var(--contrast-multiplier)) var(--scale-c-3) var(--gray-h));
  /* Other high contrast variable overrides */
}
```

### Toggle Button HTML

```html
<button class="contrast-toggle" onclick="toggleHighContrast()" aria-label="Toggle high contrast mode">
  <span class="contrast-toggle__icon">🔍</span>
  <span class="contrast-toggle__text">High Contrast</span>
</button>
```

## Integration with Other Accessibility Features

### High Contrast with Dark Mode

Consider the interaction between high contrast mode and dark mode:

```css
/* High contrast mode in light theme */
@media (prefers-contrast: more) {
  :root:not(.dark) {
    /* Light theme high contrast variables */
  }
}

/* High contrast mode in dark theme */
@media (prefers-contrast: more) {
  .dark, :root.dark {
    /* Dark theme high contrast variables */
  }
}

/* Force high contrast in light theme */
.high-contrast:not(.dark) {
  /* Light theme high contrast variables */
}

/* Force high contrast in dark theme */
.dark.high-contrast {
  /* Dark theme high contrast variables */
}
```

### High Contrast with Reduced Motion

Users who prefer high contrast may also prefer reduced motion:

```css
@media (prefers-contrast: more) and (prefers-reduced-motion: reduce) {
  :root {
    /* Combined high contrast and reduced motion variables */
    --transition-duration-standard: 0.01ms;
    --focus-ring-style: solid;
  }
}
```

## Best Practices

1. **Test with actual users** who rely on high contrast mode
2. **Use the right semantic HTML elements** to ensure proper behavior
3. **Don't disable high contrast mode** unless absolutely necessary
4. **Maintain color meaning** even in monochrome high contrast
5. **Provide sufficient information** beyond just color differences
6. **Test keyboard navigation** in high contrast mode
7. **Check color contrast ratios** to ensure WCAG compliance (minimum 4.5:1 for normal text)
8. **Consider printability** of high contrast styles
9. **Add borders to adjacent elements** of the same color
10. **Use patterns along with colors** for data visualization

## Additional Resources

- [WCAG Contrast Guidelines](https://www.w3.org/WAI/WCAG21/Understanding/contrast-minimum.html)
- [Microsoft High Contrast Documentation](https://docs.microsoft.com/en-us/windows/apps/design/accessibility/high-contrast-mode)
- [MDN prefers-contrast Documentation](https://developer.mozilla.org/en-US/docs/Web/CSS/@media/prefers-contrast)


================================================
FILE: docs/layers/components.md
================================================
# Components Layer

The Components layer provides pre-styled, reusable UI components that build upon the Defaults layer to create more complex interface elements. These components encapsulate common UI patterns with built-in accessibility, responsiveness, and theming.

## Core Concept

Components are self-contained, reusable UI elements that implement common interface patterns. They provide more complex styling than the Defaults layer and serve as the building blocks for your application's interface.

Unlike the Defaults layer (which styles HTML elements directly), the Components layer uses class-based styling to create reusable patterns that can be applied consistently throughout your application.

## Key Components

### Button Component

The button component extends the default button styling with variants:

```css
.button {
  display: inline-flex;
  align-items: center;
  justify-content: center;
  padding: var(--space-button-y, 0.7em) var(--space-button-x, 1.3em);
  font-family: var(--font-family-sans);
  font-size: var(--font-size-base);
  font-weight: var(--font-weight-medium);
  line-height: 1;
  text-align: center;
  text-decoration: none;
  color: var(--text-default);
  background-color: var(--surface-default);
  border: 1px solid var(--outline-default);
  border-radius: var(--radius-md);
  cursor: pointer;
  transition: color var(--animation-duration-fast) var(--ease-in-out),
              background-color var(--animation-duration-fast) var(--ease-in-out),
              border-color var(--animation-duration-fast) var(--ease-in-out),
              box-shadow var(--animation-duration-fast) var(--ease-in-out),
              opacity var(--animation-duration-fast) var(--ease-in-out);
  user-select: none;
}

.button:hover:not([disabled]) {
  background-color: var(--surface-subtle);
  color: var(--text-overt);
  border-color: var(--outline-overt);
}

.button:focus-visible {
  outline: var(--focus-ring-width) var(--focus-ring-style) var(--focus-ring-color);
  outline-offset: var(--focus-ring-offset);
}

.button:active:not([disabled]) {
  transform: translateY(1px);
}

.button:disabled {
  opacity: 0.6;
  cursor: not-allowed;
}

.button--small {
  font-size: var(--font-size-sm);
  padding: 0.5em 1em;
}

.button--large {
  font-size: var(--font-size-lg);
  padding: 0.8em 1.5em;
}

.button--icon {
  padding: 0.7em;
  border-radius: var(--radius-full);
}

.button__icon {
  flex-shrink: 0;
  width: 1em;
  height: 1em;
}

.button__icon--left {
  margin-right: 0.5em;
}

.button__icon--right {
  margin-left: 0.5em;
}
```

### Card Component

The card component provides a container for content with various options:

```css
.card {
  background-color: var(--surface-default);
  border-radius: var(--radius-lg);
  box-shadow: var(--shadow-sm);
  overflow: hidden;
  transition: box-shadow var(--animation-duration-normal) var(--ease-in-out),
              transform var(--animation-duration-normal) var(--ease-in-out);
}

.card--hover:hover {
  box-shadow: var(--shadow-md);
  transform: translateY(-2px);
}

.card__header {
  padding: var(--space-md) var(--space-lg);
  border-bottom: 1px solid var(--outline-subtle);
}

.card__title {
  margin: 0;
  font-size: var(--font-size-lg);
  font-weight: var(--font-weight-semibold);
  color: var(--text-overt);
}

.card__subtitle {
  margin-top: var(--space-xs);
  color: var(--text-subtle);
  font-size: var(--font-size-sm);
}

.card__body {
  padding: var(--space-lg);
}

.card__footer {
  padding: var(--space-md) var(--space-lg);
  border-top: 1px solid var(--outline-subtle);
  background-color: var(--surface-subtle);
}

.card--borderless {
  border: none;
  box-shadow: none;
}

.card--flat {
  box-shadow: none;
  border: 1px solid var(--outline-subtle);
}
```

### Alert Component

The alert component provides status and notification styling:

```css
.alert {
  padding: var(--space-md) var(--space-lg);
  border-radius: var(--radius-md);
  border-left: 4px solid var(--outline-default);
  background-color: var(--surface-default);
  color: var(--text-default);
  margin-bottom: var(--space-md);
  display: flex;
  align-items: flex-start;
}

.alert__icon {
  flex-shrink: 0;
  margin-right: var(--space-md);
  width: 24px;
  height: 24px;
}

.alert__content {
  flex-grow: 1;
}

.alert__title {
  margin-top: 0;
  margin-bottom: var(--space-xs);
  font-weight: var(--font-weight-semibold);
  color: var(--text-overt);
}

.alert__message {
  margin: 0;
}

.alert__close {
  flex-shrink: 0;
  background: none;
  border: none;
  color: var(--text-subtle);
  cursor: pointer;
  padding: 0;
  margin-left: var(--space-sm);
  transition: color var(--animation-duration-fast) var(--ease-in-out);
}

.alert__close:hover {
  color: var(--text-default);
}

.alert--info {
  border-left-color: var(--info);
  background-color: var(--surface-info);
}

.alert--success {
  border-left-color: var(--success);
  background-color: var(--surface-success);
}

.alert--warning {
  border-left-color: var(--warning);
  background-color: var(--surface-warning);
}

.alert--error {
  border-left-color: var(--error);
  background-color: var(--surface-error);
}
```

### Badge Component

The badge component provides small status indicators:

```css
.badge {
  display: inline-flex;
  align-items: center;
  justify-content: center;
  font-size: var(--font-size-xs);
  font-weight: var(--font-weight-semibold);
  line-height: 1;
  padding: 0.25em 0.75em;
  border-radius: var(--radius-full);
  background-color: var(--surface-subtle);
  color: var(--text-default);
  white-space: nowrap;
  vertical-align: middle;
}

.badge--success {
  background-color: var(--surface-success);
  color: var(--text-success);
}

.badge--warning {
  background-color: var(--surface-warning);
  color: var(--text-warning);
}

.badge--error {
  background-color: var(--surface-error);
  color: var(--text-error);
}

.badge--info {
  background-color: var(--surface-info);
  color: var(--text-info);
}

.badge--accent {
  background-color: var(--accent-subtle);
  color: var(--accent);
}

.badge--pill {
  border-radius: var(--radius-full);
  padding-left: 0.75em;
  padding-right: 0.75em;
}

.badge--outline {
  background-color: transparent;
  border: 1px solid currentColor;
}

.badge__dot {
  width: 6px;
  height: 6px;
  border-radius: 50%;
  background-color: currentColor;
  margin-right: 0.5em;
}
```

### Form Components

Enhanced form styling with validation states:

```css
.form-group {
  margin-bottom: var(--space-md);
}

.form-label {
  display: block;
  margin-bottom: var(--space-xs);
  font-weight: var(--font-weight-medium);
  color: var(--text-default);
}

.form-label--required::after {
  content: "*";
  color: var(--error);
  margin-left: 0.25em;
}

.form-help {
  display: block;
  margin-top: var(--space-xs);
  font-size: var(--font-size-sm);
  color: var(--text-subtle);
}

.form-input {
  display: block;
  width: 100%;
  padding: var(--space-sm) var(--space-md);
  font-family: inherit;
  font-size: var(--font-size-base);
  line-height: var(--line-height-normal);
  color: var(--text-default);
  background-color: var(--surface-default);
  border: 1px solid var(--outline-default);
  border-radius: var(--radius-md);
  transition: border-color var(--animation-duration-fast) var(--ease-in-out),
              box-shadow var(--animation-duration-fast) var(--ease-in-out),
              background-color var(--animation-duration-fast) var(--ease-in-out);
}

.form-input:focus {
  outline: none;
  border-color: var(--outline-focus);
  background-color: var(--input-focus-bg);
  box-shadow: 0 0 0 var(--input-focus-ring-width) var(--focus-ring-color);
}

.form-input::placeholder {
  color: var(--text-muted);
  opacity: 1;
}

.form-input:disabled, .form-input[readonly] {
  background-color: var(--surface-muted);
  color: var(--text-muted);
  cursor: not-allowed;
  opacity: 0.7;
}

.form-input--invalid {
  border-color: var(--outline-error);
}

.form-input--invalid:focus {
  border-color: var(--outline-error);
  box-shadow: 0 0 0 var(--input-focus-ring-width) rgba(var(--error-rgb), 0.25);
}

.form-error {
  display: block;
  margin-top: var(--space-xs);
  font-size: var(--font-size-sm);
  color: var(--text-error);
}

.form-select {
  appearance: none;
  background-image: url("data:image/svg+xml,..."); /* Dropdown arrow SVG */
  background-repeat: no-repeat;
  background-position: right var(--space-sm) center;
  padding-right: var(--space-xl);
}

.form-checkbox, .form-radio {
  display: flex;
  align-items: center;
  margin-bottom: var(--space-xs);
}

.form-checkbox__input, .form-radio__input {
  flex-shrink: 0;
  margin-right: var(--space-xs);
}

.form-checkbox__label, .form-radio__label {
  margin-bottom: 0;
  font-weight: var(--font-weight-normal);
}
```

### Navigation Components

Common navigation patterns:

```css
.nav {
  display: flex;
  gap: var(--space-xs);
  padding: 0;
  margin: 0;
  list-style: none;
}

.nav--vertical {
  flex-direction: column;
}

.nav__item {
  position: relative;
}

.nav__link {
  display: block;
  padding: var(--space-sm) var(--space-md);
  color: var(--text-default);
  text-decoration: none;
  border-radius: var(--radius-md);
  transition: color var(--animation-duration-fast) var(--ease-in-out),
              background-color var(--animation-duration-fast) var(--ease-in-out);
}

.nav__link:hover {
  color: var(--text-overt);
  background-color: var(--surface-subtle);
}

.nav__link:focus-visible {
  outline: var(--focus-ring-width) var(--focus-ring-style) var(--focus-ring-color);
  outline-offset: var(--focus-ring-offset);
}

.nav__link--active {
  color: var(--accent);
  background-color: var(--accent-subtle);
  font-weight: var(--font-weight-medium);
}

.breadcrumb {
  display: flex;
  flex-wrap: wrap;
  padding: 0;
  margin: 0;
  list-style: none;
}

.breadcrumb__item {
  display: flex;
  align-items: center;
}

.breadcrumb__item:not(:last-child)::after {
  content: "/";
  margin: 0 var(--space-xs);
  color: var(--text-muted);
}

.breadcrumb__link {
  color: var(--text-subtle);
  text-decoration: none;
  transition: color var(--animation-duration-fast) var(--ease-in-out);
}

.breadcrumb__link:hover {
  color: var(--text-default);
}

.breadcrumb__link--active {
  color: var(--text-default);
  font-weight: var(--font-weight-medium);
}
```

### Modal Component

A dialog/modal component:

```css
.modal {
  position: fixed;
  top: 0;
  left: 0;
  right: 0;
  bottom: 0;
  display: flex;
  align-items: center;
  justify-content: center;
  padding: var(--space-md);
  background-color: oklch(from var(--bedrock) l c h / 0.8);
  z-index: var(--z-index-50);
  opacity: 0;
  visibility: hidden;
  transition: opacity var(--animation-duration-normal) var(--ease-in-out),
              visibility var(--animation-duration-normal) var(--ease-in-out);
}

.modal--active {
  opacity: 1;
  visibility: visible;
}

.modal__dialog {
  width: 100%;
  max-width: 32rem;
  max-height: calc(100vh - var(--space-xl));
  overflow-y: auto;
  background-color: var(--surface-default);
  border-radius: var(--radius-lg);
  box-shadow: var(--shadow-lg);
  transform: translateY(20px);
  transition: transform var(--animation-duration-normal) var(--ease-out);
}

.modal--active .modal__dialog {
  transform: translateY(0);
}

.modal__header {
  padding: var(--space-md) var(--space-lg);
  border-bottom: 1px solid var(--outline-subtle);
  display: flex;
  align-items: center;
  justify-content: space-between;
}

.modal__title {
  margin: 0;
  font-size: var(--font-size-lg);
  font-weight: var(--font-weight-semibold);
  color: var(--text-overt);
  line-height: 1.2;
}

.modal__close {
  background: none;
  border: none;
  color: var(--text-subtle);
  cursor: pointer;
  padding: var(--space-xs);
  transition: color var(--animation-duration-fast) var(--ease-in-out);
  border-radius: var(--radius-full);
}

.modal__close:hover {
  color: var(--text-default);
  background-color: var(--surface-subtle);
}

.modal__close:focus-visible {
  outline: var(--focus-ring-width) var(--focus-ring-style) var(--focus-ring-color);
  outline-offset: var(--focus-ring-offset);
}

.modal__body {
  padding: var(--space-lg);
}

.modal__footer {
  padding: var(--space-md) var(--space-lg);
  border-top: 1px solid var(--outline-subtle);
  background-color: var(--surface-subtle);
  display: flex;
  gap: var(--space-sm);
  justify-content: flex-end;
}
```

### Accordion Component

A collapsible content component:

```css
.accordion {
  border: 1px solid var(--outline-subtle);
  border-radius: var(--radius-md);
  overflow: hidden;
}

.accordion__item:not(:last-child) {
  border-bottom: 1px solid var(--outline-subtle);
}

.accordion__header {
  margin: 0;
}

.accordion__button {
  display: flex;
  align-items: center;
  justify-content: space-between;
  width: 100%;
  padding: var(--space-md) var(--space-lg);
  background-color: var(--surface-default);
  color: var(--text-default);
  border: none;
  text-align: left;
  cursor: pointer;
  transition: background-color var(--animation-duration-fast) var(--ease-in-out);
}

.accordion__button:hover {
  background-color: var(--surface-subtle);
}

.accordion__button:focus-visible {
  outline: var(--focus-ring-width) var(--focus-ring-style) var(--focus-ring-color);
  outline-offset: calc(-1 * var(--focus-ring-offset));
  position: relative;
  z-index: 1;
}

.accordion__icon {
  flex-shrink: 0;
  width: 20px;
  height: 20px;
  margin-left: var(--space-sm);
  transition: transform var(--animation-duration-fast) var(--ease-in-out);
}

.accordion__item--active .accordion__icon {
  transform: rotate(180deg);
}

.accordion__content {
  padding: var(--space-md) var(--space-lg);
  background-color: var(--surface-subtle);
  display: none;
}

.accordion__item--active .accordion__content {
  display: block;
}
```

### Enhanced Focus State Handling

The Components layer includes focus state handling for components:

```css
/* Focus-visible polyfill */
.js-focus-visible .focus-visible {
  outline: var(--focus-ring-width) var(--focus-ring-style) var(--focus-ring-color);
  outline-offset: var(--focus-ring-offset);
}

.js-focus-visible :focus:not(.focus-visible) {
  outline: none;
}

/* Enhanced input focus states */
.form-input:focus-visible, 
.form-select:focus-visible, 
.form-textarea:focus-visible {
  outline: var(--input-focus-ring-width) var(--focus-ring-style) var(--focus-ring-color);
  outline-offset: var(--input-focus-ring-offset);
  border-color: var(--outline-focus);
}
```

## Using the Components Layer

### Basic Component Usage

Components are used by applying their CSS classes:

```html
<!-- Button component -->
<button class="button">Default Button</button>
<button class="button button--small">Small Button</button>
<button class="button" disabled>Disabled Button</button>

<!-- Card component -->
<div class="card">
  <div class="card__header">
    <h2 class="card__title">Card Title</h2>
    <p class="card__subtitle">Card subtitle or metadata</p>
  </div>
  <div class="card__body">
    <p>Card content goes here.</p>
  </div>
  <div class="card__footer">
    <button class="button">Action</button>
  </div>
</div>

<!-- Alert component -->
<div class="alert alert--success">
  <div class="alert__icon">✓</div>
  <div class="alert__content">
    <h4 class="alert__title">Success!</h4>
    <p class="alert__message">Your changes have been saved successfully.</p>
  </div>
  <button class="alert__close" aria-label="Close">×</button>
</div>
```

### Component Composition

Components can be combined to create more complex UI patterns:

```html
<!-- Card with form -->
<div class="card">
  <div class="card__header">
    <h2 class="card__title">Contact Form</h2>
  </div>
  <div class="card__body">
    <form>
      <div class="form-group">
        <label for="name" class="form-label form-label--required">Name</label>
        <input type="text" id="name" class="form-input" placeholder="Enter your name">
      </div>
      <div class="form-group">
        <label for="email" class="form-label form-label--required">Email</label>
        <input type="email" id="email" class="form-input" placeholder="Enter your email">
        <span class="form-help">We'll never share your email with anyone else.</span>
      </div>
      <div class="form-group">
        <label for="message" class="form-label">Message</label>
        <textarea id="message" class="form-input" rows="4"></textarea>
      </div>
    </form>
  </div>
  <div class="card__footer">
    <button class="button button--filled-accent">Submit</button>
    <button class="button">Cancel</button>
  </div>
</div>
```

### Component Variants

Components often include variants for different states or appearances:

```html
<!-- Button variants -->
<button class="button">Default Button</button>
<button class="button button--filled-accent">Accent Button</button>
<button class="button button--outline-error">Error Outline</button>
<button class="button button--text-success">Success Text</button>

<!-- Card variants -->
<div class="card">Standard Card</div>
<div class="card card--flat">Flat Card</div>
<div class="card card--hover">Hover Card</div>
<div class="card card--borderless">Borderless Card</div>

<!-- Alert variants -->
<div class="alert">Default Alert</div>
<div class="alert alert--info">Info Alert</div>
<div class="alert alert--success">Success Alert</div>
<div class="alert alert--warning">Warning Alert</div>
<div class="alert alert--error">Error Alert</div>
```

## Customizing Components

### Extending Existing Components

To extend an existing component:

```css
@layer components {
  /* Add a new button variant */
  .button--gradient {
    background: linear-gradient(to right, var(--accent), var(--secondary));
    color: white;
    border: none;
  }
  
  .button--gradient:hover:not([disabled]) {
    background: linear-gradient(to right, var(--accent-overt), var(--secondary-overt));
    color: white;
  }
  
  /* Add a new card variant */
  .card--dashboard {
    border-radius: var(--radius-sm);
    box-shadow: none;
    border: 1px solid var(--outline-subtle);
    transition: transform var(--animation-duration-fast) var(--ease-in-out);
  }
  
  .card--dashboard:hover {
    transform: translateY(-4px);
  }
}
```

### Creating New Components

To create a new component:

```css
@layer components {
  /* Create a tooltip component */
  .tooltip {
    position: relative;
    display: inline-block;
  }
  
  .tooltip__content {
    position: absolute;
    bottom: 100%;
    left: 50%;
    transform: translateX(-50%) translateY(-8px);
    padding: var(--space-xs) var(--space-sm);
    background-color: var(--surface-overt);
    color: var(--text-contrast-on-surface-overt);
    font-size: var(--font-size-sm);
    border-radius: var(--radius-sm);
    white-space: nowrap;
    pointer-events: none;
    opacity: 0;
    visibility: hidden;
    transition: opacity var(--animation-duration-fast) var(--ease-in-out),
                visibility var(--animation-duration-fast) var(--ease-in-out),
                transform var(--animation-duration-fast) var(--ease-in-out);
    z-index: var(--z-index-20);
  }
  
  .tooltip__content::after {
    content: "";
    position: absolute;
    top: 100%;
    left: 50%;
    transform: translateX(-50%);
    border-width: 4px;
    border-style: solid;
    border-color: var(--surface-overt) transparent transparent transparent;
  }
  
  .tooltip:hover .tooltip__content {
    opacity: 1;
    visibility: visible;
    transform: translateX(-50%) translateY(0);
  }
}
```

## Component Documentation

Each component should be documented with:

1. **Purpose**: What problem the component solves
2. **Usage**: When and how to use the component
3. **Variants**: Available modifiers and their purposes
4. **Accessibility**: Accessibility considerations
5. **Examples**: Sample code snippets

### Documentation Example

```md
## Card Component

The Card component is a flexible container for grouping and displaying content in a clean, organized way.

### Usage

Use cards to group related information and actions. Cards can contain text, images, links, and buttons.

### Variants

- `.card`: Standard card with shadow
- `.card--flat`: Card with border instead of shadow
- `.card--borderless`: Card without border or shadow
- `.card--hover`: Card with hover effect

### Subcomponents

- `.card__header`: Contains title and optional subtitle
- `.card__body`: Main card content area
- `.card__footer`: Action area at bottom of card

### Accessibility

- Ensure proper heading hierarchy within cards
- Use appropriate color contrast for all text
- Consider keyboard navigation if card is interactive

### Example

```html
<div class="card">
  <div class="card__header">
    <h3 class="card__title">Card Title</h3>
  </div>
  <div class="card__body">
    <p>Card content here.</p>
  </div>
  <div class="card__footer">
    <button class="button">Action</button>
  </div>
</div>
```
```

## Best Practices

1. **Follow BEM Naming**: Use Block-Element-Modifier convention for component class names
2. **Maintain Accessibility**: Ensure components meet WCAG guidelines
3. **Use Semantic Variables**: Reference semantic variables from the Theme layer
4. **Component Composition**: Design components to work well together
5. **Responsive Design**: Ensure components work well at all screen sizes
6. **Support States**: Account for hover, focus, active, and disabled states
7. **Documentation**: Document components thoroughly


================================================
FILE: docs/layers/defaults.md
================================================
# Defaults Layer

The Defaults layer defines the base styling for HTML elements, creating a consistent baseline appearance throughout your application. This layer applies semantic theme variables to raw HTML elements without requiring additional classes.

## Core Concept

While the Reset layer ensures consistent behavior by neutralizing browser defaults, the Defaults layer builds upon this by establishing a thoughtful set of default styles. Elements are styled using semantic variables from the Theme layer, creating an immediate connection to your design system right from the HTML foundation.

## Key Features

### Typography Defaults

The Defaults layer establishes a comprehensive typography system:

```css
body {
  font-family: var(--font-family-sans);
  font-size: var(--font-size-base);
  line-height: var(--line-height-normal);
  color: var(--text-default);
  background-color: var(--base);
}

h1, h2, h3, h4, h5, h6 {
  margin-top: var(--space-lg);
  margin-bottom: var(--space-sm);
  line-height: var(--line-height-tight);
  color: var(--text-overt);
  font-weight: var(--font-weight-bold);
}

h1 { font-size: var(--font-size-4xl); }
h2 { font-size: var(--font-size-3xl); }
h3 { font-size: var(--font-size-2xl); }
h4 { font-size: var(--font-size-xl); }
h5 { font-size: var(--font-size-lg); }
h6 { font-size: var(--font-size-md); }

p {
  margin-bottom: var(--space-md);
}

small {
  font-size: var(--font-size-sm);
}

strong, b {
  font-weight: var(--font-weight-bold);
  color: var(--text-overt);
}

em, i {
  font-style: italic;
}
```

### Link Styling

The Defaults layer includes comprehensive link styling with explicit states:

```css
a {
  color: var(--text-link);
  text-decoration-color: var(--text-link-underline, var(--text-link));
  text-decoration-thickness: var(--link-underline-width, 1px);
  text-underline-offset: var(--link-underline-offset, 0.15em);
  transition: color var(--animation-duration-fast) var(--ease-in-out),
              text-decoration-color var(--animation-duration-fast) var(--ease-in-out);
}

a:hover {
  color: var(--text-link-hover);
  text-decoration-color: var(--text-link-hover);
}

a:active {
  color: var(--text-link-active);
  text-decoration-color: var(--text-link-active);
}

a:visited {
  color: var(--text-link-visited);
  text-decoration-color: var(--text-link-visited);
}

a:focus-visible {
  outline: var(--focus-ring-width) var(--focus-ring-style) var(--focus-ring-color);
  outline-offset: var(--focus-ring-offset);
  text-decoration: none;
}
```

### List Styling

Lists receive appropriate styling:

```css
ul, ol {
  margin-top: var(--space-sm);
  margin-bottom: var(--space-md);
  padding-left: var(--space-lg);
}

ul {
  list-style-type: disc;
}

ol {
  list-style-type: decimal;
}

li {
  margin-bottom: var(--space-xs);
}

li > ul, li > ol {
  margin-top: var(--space-xs);
  margin-bottom: var(--space-xs);
}
```

### Table Styling

Tables receive clean, accessible styling:

```css
table {
  width: 100%;
  border-collapse: collapse;
  margin-top: var(--space-md);
  margin-bottom: var(--space-md);
  border: 1px solid var(--outline-subtle);
}

th {
  background-color: var(--surface-subtle);
  color: var(--text-default);
  font-weight: var(--font-weight-semibold);
  text-align: left;
  padding: var(--space-sm);
  border-bottom: 2px solid var(--outline-default);
}

td {
  padding: var(--space-sm);
  border-bottom: 1px solid var(--outline-subtle);
}

tr:last-child td {
  border-bottom: none;
}

tr:nth-child(even) {
  background-color: var(--surface-muted);
}

caption {
  margin-bottom: var(--space-xs);
  font-style: italic;
  color: var(--text-subtle);
  text-align: left;
}
```

### Form Element Styling

Form elements receive careful styling for consistency and accessibility:

```css
label {
  display: block;
  margin-bottom: var(--space-xs);
  font-weight: var(--font-weight-medium);
  color: var(--text-default);
}

input, select, textarea {
  display: block;
  width: 100%;
  padding: var(--space-sm) var(--space-md);
  font-family: inherit;
  font-size: var(--font-size-base);
  line-height: var(--line-height-normal);
  color: var(--text-default);
  background-color: var(--surface-default);
  border: 1px solid var(--outline-default);
  border-radius: var(--radius-md);
  transition: border-color var(--animation-duration-fast) var(--ease-in-out),
              box-shadow var(--animation-duration-fast) var(--ease-in-out),
              background-color var(--animation-duration-fast) var(--ease-in-out);
}

input:focus, select:focus, textarea:focus {
  outline: none;
  border-color: var(--outline-focus);
  background-color: var(--input-focus-bg);
  box-shadow: 0 0 0 var(--input-focus-ring-width) var(--focus-ring-color);
}

input::placeholder, textarea::placeholder {
  color: var(--text-muted);
  opacity: 1;
}

input:disabled, select:disabled, textarea:disabled {
  background-color: var(--surface-muted);
  color: var(--text-muted);
  cursor: not-allowed;
  opacity: 0.7;
}

/* Button Styling */
button, input[type="button"], input[type="submit"], input[type="reset"] {
  display: inline-block;
  padding: var(--space-button-y, 0.7em) var(--space-button-x, 1.3em);
  font-family: inherit;
  font-size: var(--font-size-base);
  font-weight: var(--font-weight-medium);
  line-height: 1;
  text-align: center;
  text-decoration: none;
  color: var(--text-default);
  background-color: var(--surface-default);
  border: 1px solid var(--outline-default);
  border-radius: var(--radius-md);
  cursor: pointer;
  transition: color var(--animation-duration-fast) var(--ease-in-out),
              background-color var(--animation-duration-fast) var(--ease-in-out),
              border-color var(--animation-duration-fast) var(--ease-in-out),
              box-shadow var(--animation-duration-fast) var(--ease-in-out);
}

button:hover:not([disabled]), 
input[type="button"]:hover:not([disabled]), 
input[type="submit"]:hover:not([disabled]), 
input[type="reset"]:hover:not([disabled]) {
  background-color: var(--surface-subtle);
  border-color: var(--outline-overt);
}

button:focus-visible, 
input[type="button"]:focus-visible, 
input[type="submit"]:focus-visible, 
input[type="reset"]:focus-visible {
  outline: var(--focus-ring-width) var(--focus-ring-style) var(--focus-ring-color);
  outline-offset: var(--focus-ring-offset);
}

button:disabled, 
input[type="button"]:disabled, 
input[type="submit"]:disabled, 
input[type="reset"]:disabled {
  background-color: var(--surface-muted);
  color: var(--text-muted);
  border-color: var(--outline-muted);
  cursor: not-allowed;
  opacity: 0.7;
}
```

### Miscellaneous Elements

Other HTML elements also receive appropriate styling:

```css
/* Horizontal Rule */
hr {
  height: 1px;
  background-color: var(--outline-subtle);
  border: none;
  margin: var(--space-lg) 0;
}

/* Blockquote */
blockquote {
  padding: var(--space-md) var(--space-lg);
  margin: var(--space-md) 0;
  border-left: 4px solid var(--outline-default);
  background-color: var(--surface-subtle);
  color: var(--text-subtle);
  font-style: italic;
}

/* Code and Pre */
code {
  font-family: var(--font-family-mono);
  font-size: 0.9em;
  color: var(--text-highlight-overt);
  background-color: var(--highlight-bg-subtle);
  padding: 0.2em 0.4em;
  border-radius: var(--radius-sm);
}

pre {
  font-family: var(--font-family-mono);
  background-color: var(--surface-subtle);
  padding: var(--space-md);
  margin: var(--space-md) 0;
  border-radius: var(--radius-md);
  overflow-x: auto;
  border: 1px solid var(--outline-subtle);
}

pre code {
  background-color: transparent;
  padding: 0;
  color: var(--text-default);
}

/* Images */
img {
  max-width: 100%;
  height: auto;
  display: block;
  border-radius: var(--radius-sm);
}

figure {
  margin: var(--space-md) 0;
}

figcaption {
  margin-top: var(--space-xs);
  font-size: var(--font-size-sm);
  color: var(--text-subtle);
}
```

## Enhanced Accessibility Features

### Focus States

The Defaults layer includes enhanced focus state handling:

```css
/* Global focus style for keyboard navigation */
:focus-visible {
  outline: var(--focus-ring-width) var(--focus-ring-style) var(--focus-ring-color);
  outline-offset: var(--focus-ring-offset);
}

/* Remove default focus style for mouse users */
:focus:not(:focus-visible) {
  outline: none;
}
```

### Custom Form Element States

Form elements receive accessible styling for all states:

```css
/* Custom checkbox styling */
input[type="checkbox"], input[type="radio"] {
  width: auto;
  margin-right: var(--space-xs);
}

input[type="checkbox"]:focus-visible, input[type="radio"]:focus-visible {
  outline: var(--focus-ring-width) var(--focus-ring-style) var(--focus-ring-color);
  outline-offset: var(--focus-ring-offset);
}

/* Custom select styling */
select {
  appearance: none;
  background-image: url("data:image/svg+xml,..."); /* Dropdown arrow SVG */
  background-repeat: no-repeat;
  background-position: right var(--space-sm) center;
  padding-right: var(--space-xl);
}
```

### Screen Reader Utilities

The Defaults layer includes necessary screen reader utilities:

```css
.sr-only {
  position: absolute;
  width: 1px;
  height: 1px;
  padding: 0;
  margin: -1px;
  overflow: hidden;
  clip: rect(0, 0, 0, 0);
  white-space: nowrap;
  border-width: 0;
}

.not-sr-only {
  position: static;
  width: auto;
  height: auto;
  padding: 0;
  margin: 0;
  overflow: visible;
  clip: auto;
  white-space: normal;
}
```

## Using the Defaults Layer

### Default HTML Elements

The Defaults layer applies styling to HTML elements automatically, without requiring additional classes:

```html
<h1>Page Title</h1>
<p>This is a paragraph with a <a href="#">link</a> and <strong>strong text</strong>.</p>

<ul>
  <li>List item one</li>
  <li>List item two</li>
</ul>

<table>
  <caption>Sample Table</caption>
  <thead>
    <tr>
      <th>Name</th>
      <th>Role</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>Alice</td>
      <td>Developer</td>
    </tr>
    <tr>
      <td>Bob</td>
      <td>Designer</td>
    </tr>
  </tbody>
</table>

<form>
  <div>
    <label for="name">Name</label>
    <input type="text" id="name" placeholder="Enter your name">
  </div>
  <button type="submit">Submit</button>
</form>
```

### Combining with Components and Utilities

The Defaults layer provides a solid foundation that can be enhanced with Components and Utilities layers:

```html
<!-- Default styles applied automatically -->
<h2>Product Features</h2>

<!-- Enhanced with component classes -->
<div class="card">
  <h3>Feature Name</h3>
  <p>Feature description goes here.</p>
</div>

<!-- Enhanced with utility classes -->
<button class="button-filled-accent mt-md">Get Started</button>
```

## Customizing the Defaults Layer

### Extending Default Styles

To extend or modify default styles, add to the Defaults layer:

```css
@layer defaults {
  /* Modify existing default styles */
  h1 {
    font-size: var(--font-size-5xl);
    letter-spacing: var(--letter-spacing-tight);
  }
  
  /* Add styling for additional elements */
  details {
    border: 1px solid var(--outline-subtle);
    border-radius: var(--radius-md);
    padding: var(--space-sm);
    margin-bottom: var(--space-md);
  }
  
  summary {
    font-weight: var(--font-weight-semibold);
    cursor: pointer;
    padding: var(--space-xs) 0;
  }
  
  details[open] summary {
    margin-bottom: var(--space-sm);
    border-bottom: 1px solid var(--outline-subtle);
  }
}
```

### Creating Variations

For significant variations, consider using cascade layers:

```css
@layer defaults.print {
  @media print {
    body {
      font-size: 12pt;
      color: black;
      background: none;
    }
    
    a {
      color: black;
      text-decoration: underline;
    }
    
    table, th, td {
      border: 1px solid #ddd;
    }
  }
}
```

## Complete Reference

### Typography Elements
- `body`: Base typography
- `h1`-`h6`: Headings
- `p`: Paragraphs
- `small`, `strong`, `b`, `em`, `i`: Text formatting
- `a`: Links (with states)
- `code`, `pre`: Code blocks
- `blockquote`: Quotes

### List Elements
- `ul`, `ol`: Lists
- `li`: List items

### Table Elements
- `table`: Tables
- `th`, `td`: Table cells
- `caption`: Table caption
- `tr`: Table rows

### Form Elements
- `form`: Form container
- `label`: Form labels
- `input`: Text inputs
- `input[type="checkbox"]`, `input[type="radio"]`: Checkboxes and radio buttons
- `select`, `option`: Dropdown menus
- `textarea`: Multi-line text input
- `button`, `input[type="button"]`, `input[type="submit"]`, `input[type="reset"]`: Buttons

### Miscellaneous Elements
- `hr`: Horizontal rule
- `img`: Images
- `figure`, `figcaption`: Image with caption
- `details`, `summary`: Accordion elements

## Best Practices

1. **Use Semantic HTML**: The Defaults layer is designed to work best with semantic HTML elements
2. **Preserve Default Styling**: Avoid overriding the Defaults layer for specific components; use the Components layer instead
3. **Maintain Accessibility**: When customizing, ensure you maintain or enhance accessibility features
4. **Test Responsively**: Default styles should work well at all viewport sizes
5. **Consider Print Styles**: Include print-specific adjustments for better printed output


================================================
FILE: docs/layers/engine.md
================================================
# Engine Layer

The Engine layer is the computational heart of our CSS framework, containing the complex calculations and functions that power dynamic color manipulation, contrast calculations, and other mathematical operations.

## Core Concept

While the Tokens layer defines raw values and the Theme layer applies semantic meaning, the Engine layer provides the mathematical machinery to dynamically compute values based on context. This enables powerful features like automatic contrast adjustment, color transformations, and theme adaptations.

The Engine layer leverages modern CSS functions including:
- `calc()` for numerical computations
- `clamp()` for value constraints
- `oklch()` for color manipulation
- Color adjustment functions for transforms

## Key Features

### Auto-Contrast Calculation

The most prominent feature of the Engine layer is the automatic contrast calculation system. This dynamically adjusts text color based on background color to ensure readability:

```css
--auto-contrast-text: oklch(
  from var(--bg, var(--base))
  clamp(0.1, (var(--l-threshold, 0.65) / l - 1) * 999, 0.98)
  min(c, var(--c-threshold, 0.08))
  h
);
```

This complex calculation:
1. Takes the background color (`--bg` or falls back to `--base`)
2. Calculates an appropriate lightness value that contrasts with the background
3. Constrains the chroma (color intensity) to prevent vibrating text
4. Maintains the same hue for color harmony

### Color Transformations

The Engine provides systematic color transformations for creating consistent color variants:

```css
/* Muted variant - reduced chroma, slightly adjusted lightness */
--color-to-muted: oklch(
  from var(--color-base)
  calc(l * 0.97)
  calc(c * 0.3)
  h
);

/* Subtle variant - higher lightness, much lower chroma */
--color-to-subtle: oklch(
  from var(--color-base)
  calc(l * 1.15)
  calc(c * 0.12)
  h
);

/* Overt variant - slightly lower lightness, higher chroma */
--color-to-overt: oklch(
  from var(--color-base)
  calc(l * 0.85)
  calc(c * 1.2)
  h
);
```

### Dark Mode Adaptations

The Engine includes calculations for automatically adapting colors to dark mode:

```css
/* Dark mode color inversion - maintains similar perceived contrast */
--color-dark-mode: oklch(
  from var(--color-base)
  calc(1 - l * 0.85)
  calc(c * 0.85)
  calc(h)
);
```

### Responsive Value Scaling

The Engine provides calculations for contextually scaling values based on viewport size:

```css
/* Fluid typography scaling */
--responsive-text: clamp(
  var(--min-size, 1rem),
  calc(var(--min-size, 1rem) + (var(--max-size, 1.5rem) - var(--min-size, 1rem)) * 
    ((100vw - var(--min-viewport, 20rem)) / (var(--max-viewport, 80rem) - var(--min-viewport, 20rem)))),
  var(--max-size, 1.5rem)
);
```

## How the Engine Works

### Color Space Explanation

The Engine primarily uses OKLCH color space, which offers significant advantages:

- **Perceptual Uniformity**: Equal steps in OKLCH values correspond to equal perceived changes in color
- **Intuitive Control**: Separate control over lightness, chroma, and hue
- **Wider Gamut**: Access to colors outside sRGB
- **Better Interpolation**: More natural-looking transitions between colors

OKLCH parameters:
- **L (Lightness)**: 0-1 value representing perceptual lightness
- **C (Chroma)**: 0+ value representing color intensity (similar to saturation)
- **H (Hue)**: 0-360 degree value representing the color

### Contrast Calculation Details

The automatic contrast formula works as follows:

1. It extracts the lightness (l) from the background color
2. Compares it against a threshold (defaults to 0.65)
3. If the background is lighter than the threshold, it chooses a dark text color
4. If the background is darker than the threshold, it chooses a light text color
5. The chroma is reduced to improve readability
6. The hue is maintained for design consistency

```css
clamp(0.1, (var(--l-threshold, 0.65) / l - 1) * 999, 0.98)
```

This formula:
- Returns a value near 0.1 (dark) for light backgrounds
- Returns a value near 0.98 (light) for dark backgrounds
- Creates a sharp transition around the threshold value

### Color Mathematics in CSS

The Engine makes extensive use of CSS's color math capabilities:

```css
/* Extracting components from colors */
oklch(from var(--color) l c h)

/* Mathematical operations on components */
oklch(from var(--color) calc(l + 0.1) c h) /* Lighten */
oklch(from var(--color) calc(l - 0.1) c h) /* Darken */
oklch(from var(--color) l calc(c * 1.5) h) /* Saturate */
oklch(from var(--color) l calc(c * 0.5) h) /* Desaturate */
oklch(from var(--color) l c calc(h + 180)) /* Complement */
```

## Using the Engine Layer

### Direct Usage (Advanced)

The Engine layer is primarily used internally by the framework, but advanced users can leverage its capabilities directly:

```css
.custom-element {
  background-color: var(--custom-bg, var(--surface-default));
  color: oklch(
    from var(--custom-bg, var(--surface-default))
    clamp(0.1, (0.65 / l - 1) * 999, 0.98)
    min(c, 0.08)
    h
  );
}
```

### Extending the Engine

To add new calculations to the Engine layer:

```css
@layer engine {
  :root {
    /* Custom calculation for semi-transparent overlay */
    --overlay-color: oklch(
      from var(--base)
      calc(l * 0.8)
      calc(c * 0.5)
      h / 0.85
    );
    
    /* Custom calculation for text shadow color */
    --text-shadow-color: oklch(
      from var(--text-default)
      calc(l * 0.7)
      c
      h / 0.6
    );
  }
}
```

## Engine Variables Reference

### Contrast Calculations

```css
--auto-contrast-text
--auto-contrast-border
--high-contrast-text
--high-contrast-border
```

### Color Transformations

```css
--color-to-muted
--color-to-subtle
--color-to-overt
--color-to-dark-mode
--color-to-high-contrast
```

### Mathematical Helpers

```css
--l-delta-1-up
--l-delta-2-up
--l-delta-3-up
--l-delta-1-down
--l-delta-2-down
--l-delta-3-down
--c-delta-1-up
--c-delta-1-down
```

## Technical Limitations

While the Engine layer is powerful, it has some limitations:

1. **Browser Support**: Advanced color calculations require modern browsers
2. **Computation Cost**: Complex calculations may impact performance
3. **Debugging Complexity**: Dynamic calculated values can be harder to debug

## Best Practices

1. Use the Engine calculations through semantic variables from the Theme layer
2. Reserve direct usage of Engine calculations for advanced scenarios
3. Test across browsers to ensure calculations behave consistently
4. Consider providing fallbacks for browsers that don't support advanced calculations
5. Document custom calculations thoroughly


================================================
FILE: docs/layers/layouts.md
================================================
# Layouts Layer

The Layouts layer provides reusable layout patterns and structural components that help organize content on the page. These layout components use container queries for component-level responsive design, making them truly reusable regardless of their context.

## Core Concept

Layout components focus on the arrangement and positioning of elements rather than their visual appearance. They provide the structural foundation upon which you can build more complex interfaces.

The Layouts layer has the highest specificity in the cascade, allowing layout components to override other styles when necessary:

```css
@layer reset, tokens, engine, theme, palette, defaults, components, utilities, layouts;
```

Unlike traditional layout systems that rely on viewport-based media queries, our layout components use container queries to adapt based on their own size rather than the size of the viewport. This makes them more flexible and reusable.

## Key Features

### Container Query Support

All layout components use container queries to adapt their layout based on their container size:

```css
.l-container {
  container-type: var(--l-container-type, inline-size);
  container-name: var(--l-container-name, layout);
}

.l-grid {
  display: grid;
  gap: var(--l-grid-gap, var(--space-md));
  grid-template-columns: repeat(auto-fit, minmax(min(100%, var(--l-grid-min-item-size, 15rem)), 1fr));
  container-type: inline-size;
  container-name: layout-grid;
}

@container layout-grid (min-width: var(--cq-bp-sm, 30em)) {
  /* Layout changes at container width of 30em */
}

@container layout-grid (min-width: var(--cq-bp-md, 45em)) {
  /* Layout changes at container width of 45em */
}
```

### Customization via CSS Variables

Layout components are highly customizable through CSS variables:

```css
.l-grid {
  --l-grid-gap: var(--space-lg); /* Override default gap */
  --l-grid-min-item-size: 20rem; /* Override default minimum item size */
}

.l-split {
  --l-split-fraction: 2fr; /* Change the split ratio */
  --l-split-gap: var(--space-xl); /* Override default gap */
  --l-split-breakpoint: var(--cq-bp-md); /* Custom breakpoint */
}
```

### Progressive Enhancement

Layouts are designed with progressive enhancement in mind, working with and without container query support:

```css
.l-row {
  display: flex;
  flex-wrap: var(--l-row-wrap, wrap);
  gap: var(--l-row-gap, var(--space-md));
  container-type: inline-size;
  container-name: layout-row;
  flex-direction: column; /* Default stacked layout */
  align-items: var(--l-row-align-stacked, stretch);
}

/* With container queries */
@container layout-row (min-width: var(--l-row-stack-breakpoint, var(--cq-bp-xs, 20em))) {
  .l-row:not(.l-row--force-stack) {
    flex-direction: var(--l-row-direction, row);
    align-items: var(--l-row-align, center);
    justify-content: var(--l-row-justify, flex-start);
  }
}

/* Without container queries - can use a forced class */
.l-row--no-stack {
  flex-direction: var(--l-row-direction, row);
  align-items: var(--l-row-align, center);
  justify-content: var(--l-row-justify, flex-start);
}
```

## Layout Components

### Grid Layout

A responsive grid layout that automatically adjusts columns based on container width:

```css
.l-grid {
  display: grid;
  gap: var(--l-grid-gap, var(--space-md));
  grid-template-columns: repeat(auto-fit, minmax(min(100%, var(--l-grid-min-item-size, 15rem)), 1fr));
  container-type: inline-size;
  container-name: layout-grid;
}

.l-grid > * {
  min-width: 0; /* Prevent grid items from overflowing */
}
```

Usage:

```html
<div class="l-grid">
  <div class="card">Grid Item 1</div>
  <div class="card">Grid Item 2</div>
  <div class="card">Grid Item 3</div>
  <div class="card">Grid Item 4</div>
</div>
```

Customization:

```html
<div class="l-grid" style="--l-grid-min-item-size: 20rem; --l-grid-gap: var(--space-lg);">
  <!-- Grid items -->
</div>
```

### Two-Column Layout

A simple two-column layout that stacks on smaller containers:

```css
.l-two-col {
  display: grid;
  gap: var(--l-two-col-gap, var(--space-lg));
  container-type: inline-size;
  container-name: layout-two-col;
  grid-template-columns: 1fr; /* Default to single column */
}

.l-two-col > * {
  min-width: 0;
}

@container layout-two-col (min-width: var(--l-two-col-breakpoint, var(--cq-bp-sm, 30em))) {
  .l-two-col {
    grid-template-columns: repeat(2, 1fr); /* Two equal columns at breakpoint */
  }
}
```

### Split Layout

A two-column layout with customizable proportions:

```css
.l-split {
  display: grid;
  grid-template-columns: 1fr; /* Default to single column */
  gap: var(--l-split-gap, var(--space-lg));
  container-type: inline-size;
  container-name: layout-split;
}

.l-split > * {
  min-width: 0;
}

@container layout-split (min-width: var(--l-split-breakpoint, var(--cq-bp-sm, 30em))) {
  .l-split {
    grid-template-columns: var(--l-split-fraction, 1fr) 1fr; /* Customizable split ratio */
  }
}

.l-split--no-stack {
  grid-template-columns: var(--l-split-fraction, 1fr) 1fr; /* Always use columns */
}
```

Usage:

```html
<div class="l-split" style="--l-split-fraction: 2fr;">
  <div class="bg-surface-subtle p-md">Wider column (2fr)</div>
  <div class="bg-surface-subtle p-md">Narrower column (1fr)</div>
</div>
```

### Row Layout

A flexible row layout that stacks on smaller containers:

```css
.l-row {
  display: flex;
  flex-wrap: var(--l-row-wrap, wrap);
  gap: var(--l-row-gap, var(--space-md));
  container-type: inline-size;
  container-name: layout-row;
  flex-direction: column; /* Default to stacked */
  align-items: var(--l-row-align-stacked, stretch);
}

.l-row > * {
  min-width: 0;
}

@container layout-row (min-width: var(--l-row-stack-breakpoint, var(--cq-bp-xs, 20em))) {
  .l-row:not(.l-row--force-stack) {
    flex-direction: var(--l-row-direction, row);
    align-items: var(--l-row-align, center);
    justify-content: var(--l-row-justify, flex-start);
  }
}

.l-row--no-stack {
  flex-direction: var(--l-row-direction, row);
  align-items: var(--l-row-align, center);
  justify-content: var(--l-row-justify, flex-start);
}
```

Usage:

```html
<div class="l-row" style="--l-row-justify: space-between;">
  <div>Start content</div>
  <div>Middle content</div>
  <div>End content</div>
</div>
```

### Stack Layout

A vertical stack with consistent spacing:

```css
.l-stack {
  display: flex;
  flex-direction: column;
  justify-content: var(--l-stack-justify, flex-start);
  align-items: var(--l-stack-align, stretch);
  gap: var(--l-stack-gap, var(--space-md));
}
```

Usage:

```html
<div class="l-stack" style="--l-stack-gap: var(--space-lg);">
  <h2>Heading</h2>
  <p>Paragraph text</p>
  <button class="button">Action</button>
</div>
```

### Cluster Layout

A flexible layout for grouping related elements:

```css
.l-cluster {
  display: flex;
  flex-wrap: wrap;
  gap: var(--l-cluster-gap, var(--space-sm));
  justify-content: var(--l-cluster-justify, flex-start);
  align-items: var(--l-cluster-align, center);
}
```

Usage:

```html
<div class="l-cluster">
  <span class="badge">Tag 1</span>
  <span class="badge">Tag 2</span>
  <span class="badge">Long Tag 3</span>
  <span class="badge">Tag 4</span>
</div>
```

### Reel Layout

A horizontally scrolling container:

```css
.l-reel {
  display: flex;
  gap: var(--l-reel-gap, var(--space-md));
  overflow-x: auto;
  overflow-y: hidden;
  scrollbar-width: thin;
  scrollbar-color: var(--scrollbar-thumb-color) var(--scrollbar-track-color);
  -webkit-overflow-scrolling: touch;
}

.l-reel--no-scrollbar {
  scrollbar-width: none;
}

.l-reel--no-scrollbar::-webkit-scrollbar {
  display: none;
}

.l-reel > * {
  flex-shrink: 0;
}

.l-reel > img {
  height: 100%;
  max-height: var(--l-reel-item-max-height, 100%);
  width: auto;
  flex-basis: auto;
}
```

Usage:

```html
<div class="l-reel">
  <div class="card" style="width: 300px;">Card 1</div>
  <div class="card" style="width: 300px;">Card 2</div>
  <div class="card" style="width: 300px;">Card 3</div>
  <div class="card" style="width: 300px;">Card 4</div>
</div>
```

### Switcher Layout

A layout that switches between row and column based on container width:

```css
.l-switcher {
  display: flex;
  flex-wrap: wrap;
  gap: var(--l-switcher-gap, var(--space-sm));
}

.l-switcher > * {
  flex-grow: 1;
  flex-basis: calc((var(--l-switcher-threshold, 20rem) - 100%) * 999);
}
```

Usage:

```html
<div class="l-switcher" style="--l-switcher-threshold: 25rem;">
  <div class="card">Section 1</div>
  <div class="card">Section 2</div>
</div>
```

### Spread Layout

A layout for distributing items evenly:

```css
.l-spread {
  display: flex;
  flex-direction: var(--l-spread-direction, row);
  justify-content: space-between;
  align-items: var(--l-spread-align, center);
  gap: var(--l-spread-gap, var(--space-md));
}
```

Usage:

```html
<div class="l-spread">
  <div>Left content</div>
  <div>Right content</div>
</div>
```

## Wrapper Components

### Padding Wrapper

Adds consistent padding to an element:

```css
.l-pad {
  padding: var(--l-pad-padding, var(--space-md));
  padding-inline: var(--l-pad-padding-x, var(--l-pad-padding, var(--space-md)));
  padding-block: var(--l-pad-padding-y, var(--l-pad-padding, var(--space-md)));
}
```

Usage:

```html
<div class="l-pad" style="--l-pad-padding-x: var(--space-lg); --l-pad-padding-y: var(--space-md);">
  Content with custom padding
</div>
```

### Center Content

Centers content horizontally with a maximum width:

```css
.l-center-content {
  box-sizing: content-box;
  margin-inline: auto;
  max-width: var(--l-center-content-max-width, var(--width-container-max, 60ch));
  padding-inline: var(--l-center-content-gutter, 0);
  text-align: var(--l-center-content-text-align, initial);
}
```

Usage:

```html
<div class="l-center-content" style="--l-center-content-max-width: 80ch; --l-center-content-gutter: var(--space-md);">
  <p>Centered content with a maximum width and gutters.</p>
</div>
```

### Cover Layout

Creates a full-height layout with centered content:

```css
.l-cover {
  display: grid;
  place-content: var(--l-cover-place-content, center);
  place-items: var(--l-cover-place-items, center);
  padding: var(--l-cover-padding, var(--space-lg));
  min-height: var(--l-cover-min-height, 50vh);
  overflow: hidden;
  text-align: var(--l-cover-text-align, center);
}
```

Usage:

```html
<div class="l-cover" style="--l-cover-min-height: 100vh;">
  <div class="l-stack">
    <h1>Centered Cover Layout</h1>
    <p>This content is centered vertically and horizontally.</p>
    <button class="button button-filled-accent">Action</button>
  </div>
</div>
```

### Frame Layout

Creates a responsive container for media with a fixed aspect ratio:

```css
.l-frame {
  position: relative;
  overflow: hidden;
  aspect-ratio: var(--l-frame-ratio, 16 / 9);
}

.l-frame > :first-child {
  position: absolute;
  top: 0;
  left: 0;
  width: 100%;
  height: 100%;
  object-fit: var(--l-frame-object-fit, cover);
  object-position: var(--l-frame-object-position, center);
}
```

Usage:

```html
<div class="l-frame" style="--l-frame-ratio: 1 / 1;">
  <img src="image.jpg" alt="Square framed image">
</div>
```

### Center Layout

Centers content horizontally, vertically, or both:

```css
.l-center {
  display: flex;
  justify-content: var(--l-center-justify, center);
  align-items: var(--l-center-align, center);
  min-height: var(--l-center-min-height, auto);
  padding: var(--l-center-padding, 0);
}

.l-center--h {
  align-items: initial;
}

.l-center--v {
  justify-content: initial;
}
```

Usage:

```html
<div class="l-center" style="min-height: 200px;">
  <div>Centered content</div>
</div>
```

## Complex Layout Patterns

### Sidebar Layout

A sidebar layout with customizable width and position:

```css
.l-sidebar {
  display: grid;
  gap: var(--l-sidebar-gap, var(--space-lg));
  container-type: inline-size;
  container-name: layout-sidebar;
  grid-template-areas: "content" "sidebar"; /* Default stacked layout */
}

.l-sidebar > *:not(.l-sidebar__aside) {
  grid-area: content;
  min-width: 0;
}

.l-sidebar > .l-sidebar__aside {
  grid-area: sidebar;
  min-width: 0;
  width: 100%;
}

@container layout-sidebar (min-width: var(--l-sidebar-breakpoint, var(--cq-bp-md, 45em))) {
  .l-sidebar {
    grid-template-columns: var(--l-sidebar-width, minmax(15rem, 25%)) 1fr;
    grid-template-areas: "sidebar content";
  }
  
  .l-sidebar > .l-sidebar__aside {
    width: auto;
  }
  
  .l-sidebar--right {
    grid-template-columns: 1fr var(--l-sidebar-width, minmax(15rem, 25%));
    grid-template-areas: "content sidebar";
  }
}
```

Usage:

```html
<div class="l-sidebar">
  <main>
    <h1>Main Content</h1>
    <p>This is the main content area.</p>
  </main>
  <aside class="l-sidebar__aside">
    <nav>
      <h2>Navigation</h2>
      <ul>
        <li><a href="#">Link 1</a></li>
        <li><a href="#">Link 2</a></li>
        <li><a href="#">Link 3</a></li>
      </ul>
    </nav>
  </aside>
</div>
```

### Standard Page Layout

A common layout with header, main content, and footer:

```css
.l-standard-page {
  display: grid;
  grid-template-rows: auto 1fr auto;
  min-height: var(--l-standard-page-min-height, 100vh);
  gap: var(--l-standard-page-gap, 0);
}

.l-standard-page > * {
  min-width: 0;
}

.l-standard-page__header {
  grid-row: 1;
}

.l-standard-page__main {
  grid-row: 2;
}

.l-standard-page__footer {
  grid-row: 3;
}
```

Usage:

```html
<div class="l-standard-page">
  <header class="l-standard-page__header">
    <nav>Header content</nav>
  </header>
  <main class="l-standard-page__main">
    <div class="l-center-content l-pad">
      <h1>Main Content</h1>
      <p>This is the main content area.</p>
    </div>
  </main>
  <footer class="l-standard-page__footer">
    <div class="l-center-content l-pad">
      Footer content
    </div>
  </footer>
</div>
```

### Media Layout

A layout for image and text combinations:

```css
.l-media {
  display: flex;
  align-items: var(--l-media-align, flex-start);
  gap: var(--l-media-gap, var(--space-md));
}

.l-media > :first-child {
  flex-shrink: 0;
}

.l-media > :last-child {
  flex-grow: 1;
  min-width: 0;
}

.l-media--reverse {
  flex-direction: row-reverse;
}
```

Usage:

```html
<div class="l-media">
  <img src="avatar.jpg" alt="User avatar" width="64" height="64">
  <div>
    <h3>John Doe</h3>
    <p>Lorem ipsum dolor sit amet, consectetur adipiscing elit.</p>
  </div>
</div>
```

### Tabs Layout

A flexible tabs layout:

```css
.l-tabs {
  display: flex;
  flex-direction: column;
  gap: var(--l-tabs-gap, var(--space-md));
}

.l-tabs__list {
  flex-shrink: 0;
}

.l-tabs__panel {
  flex-grow: 1;
  min-height: 0;
}

.l-tabs--bottom {
  flex-direction: column-reverse;
}

.l-tabs--left {
  flex-direction: row;
}

.l-tabs--right {
  flex-direction: row-reverse;
}

.l-tabs--left > .l-tabs__panel,
.l-tabs--right > .l-tabs__panel {
  min-width: 0;
}

.l-tabs--left > .l-tabs__list,
.l-tabs--right > .l-tabs__list {
  width: var(--l-tabs-side-width, max-content);
  flex-shrink: 0;
}
```

Usage:

```html
<div class="l-tabs">
  <div class="l-tabs__list">
    <button class="button" aria-selected="true">Tab 1</button>
    <button class="button">Tab 2</button>
    <button class="button">Tab 3</button>
  </div>
  <div class="l-tabs__panel">
    Tab 1 content
  </div>
</div>
```

## Using the Layouts Layer

### Basic Usage

Layout components are used by applying their CSS classes:

```html
<!-- Basic grid layout -->
<div class="l-grid">
  <div class="card">Grid Item 1</div>
  <div class="card">Grid Item 2</div>
  <div class="card">Grid Item 3</div>
</div>

<!-- Stack layout for vertical content -->
<div class="l-stack gap-lg">
  <h2>Stack Layout</h2>
  <p>Content stacked vertically with consistent spacing.</p>
  <button class="button">Action</button>
</div>
```

### Customizing Layouts

Layouts can be customized using CSS variables:

```html
<!-- Customized grid layout -->
<div class="l-grid" style="--l-grid-min-item-size: 20rem; --l-grid-gap: var(--space-lg);">
  <div class="card">Grid Item 1</div>
  <div class="card">Grid Item 2</div>
  <div class="card">Grid Item 3</div>
</div>

<!-- Customized split layout -->
<div class="l-split" style="--l-split-fraction: 2fr; --l-split-gap: var(--space-xl);">
  <div class="bg-surface-subtle p-md">Wider column (2fr)</div>
  <div class="bg-surface-subtle p-md">Narrower column (1fr)</div>
</div>
```

### Combining with Components and Utilities

Layouts work well with components and utility classes:

```html
<div class="l-standard-page">
  <header class="l-standard-page__header bg-surface-default shadow-sm">
    <div class="l-center-content l-pad">
      <div class="l-spread">
        <h1 class="text-xl font-bold">Site Title</h1>
        <nav class="l-row gap-sm">
          <a href="#" class="text-link">Home</a>
          <a href="#" class="text-link">About</a>
          <a href="#" class="text-link">Contact</a>
        </nav>
      </div>
    </div>
  </header>
  
  <main class="l-standard-page__main bg-base">
    <div class="l-center-content l-pad">
      <div class="l-stack gap-xl">
        <section>
          <h2 class="text-2xl font-bold mb-md">Featured Content</h2>
          <div class="l-grid">
            <div class="card">
              <div class="card__body">
                <h3>Card 1</h3>
                <p>Card content here.</p>
              </div>
            </div>
            <div class="card">
              <div class="card__body">
                <h3>Card 2</h3>
                <p>Card content here.</p>
              </div>
            </div>
            <div class="card">
              <div class="card__body">
                <h3>Card 3</h3>
                <p>Card content here.</p>
              </div>
            </div>
          </div>
        </section>
        
        <section>
          <h2 class="text-2xl font-bold mb-md">Sidebar Example</h2>
          <div class="l-sidebar">
            <div class="bg-surface-default p-lg rounded-md">
              <h3>Main Content</h3>
              <p>This is the main content area.</p>
            </div>
            <aside class="l-sidebar__aside bg-surface-subtle p-md rounded-md">
              <h3>Sidebar</h3>
              <p>This is the sidebar content.</p>
            </aside>
          </div>
        </section>
      </div>
    </div>
  </main>
  
  <footer class="l-standard-page__footer bg-surface-default border-t border-outline-subtle">
    <div class="l-center-content l-pad">
      <div class="l-spread">
        <p class="text-subtle">© 2023 Company Name</p>
        <div class="l-cluster">
          <a href="#" class="text-link">Terms</a>
          <a href="#" class="text-link">Privacy</a>
          <a href="#" class="text-link">Contact</a>
        </div>
      </div>
    </div>
  </footer>
</div>
```

## Extending the Layouts Layer

### Creating New Layout Components

To create a new layout component:

```css
@layer layouts {
  /* Creating a new "card grid" layout component */
  .l-card-grid {
    display: grid;
    grid-template-columns: repeat(auto-fill, minmax(min(100%, var(--l-card-grid-min-size, 18rem)), 1fr));
    gap: var(--l-card-grid-gap, var(--space-lg));
    container-type: inline-size;
    container-name: layout-card-grid;
  }
  
  .l-card-grid > * {
    height: 100%;
    display: flex;
    flex-direction: column;
  }
  
  .l-card-grid-item__media {
    aspect-ratio: var(--l-card-grid-media-ratio, 16 / 9);
    overflow: hidden;
  }
  
  .l-card-grid-item__media img {
    width: 100%;
    height: 100%;
    object-fit: cover;
  }
  
  .l-card-grid-item__content {
    flex: 1;
    display: flex;
    flex-direction: column;
  }
  
  .l-card-grid-item__footer {
    margin-top: auto;
  }
}
```

### Extending Existing Layout Components

To extend an existing layout component:

```css
@layer layouts {
  /* Adding a variant to the sidebar layout */
  .l-sidebar--sticky-aside {
    height: 100%;
  }
  
  .l-sidebar--sticky-aside > .l-sidebar__aside {
    position: sticky;
    top: var(--l-sidebar-sticky-top, 1rem);
    max-height: var(--l-sidebar-sticky-max-height, calc(100vh - 2rem));
    overflow-y: auto;
  }
  
  /* Adding a new variant to the standard page layout */
  .l-standard-page--fixed-header .l-standard-page__header {
    position: sticky;
    top: 0;
    z-index: var(--z-index-20);
  }
}
```

## Best Practices

1. **Separation of Concerns**: Keep layout separate from visual styling
2. **Container Queries**: Use container queries for true component responsiveness
3. **Progressive Enhancement**: Provide fallbacks for browsers without container query support
4. **Customization**: Use CSS variables for customization rather than adding variants
5. **Semantics**: Use semantic HTML within your layout components
6. **Accessibility**: Ensure layouts maintain good accessibility
7. **Performance**: Keep layouts simple and avoid unnecessary nesting

### Guidelines for Using Layouts

1. **Choose the Right Layout**: Select the layout that best matches your content structure
2. **Combine Layouts**: Nest layouts to create complex structures
3. **Mind the Content**: Ensure content flows well within the chosen layout
4. **Responsive Considerations**: Test layouts at various container sizes
5. **Customize with Variables**: Use CSS variables to adapt layouts to specific needs

## Complete Reference

The Layouts layer includes these layout components:

### Grid Layouts
- `.l-grid`: Responsive auto-fit grid layout
- `.l-two-col`: Simple two-column layout
- `.l-split`: Two-column layout with customizable proportions

### Flexbox Layouts
- `.l-row`: Horizontal row that stacks at small sizes
- `.l-stack`: Vertical stack with consistent spacing
- `.l-cluster`: Flexible layout for grouped elements
- `.l-reel`: Horizontally scrolling container
- `.l-switcher`: Layout that switches between row and column
- `.l-spread`: Layout for distributing items evenly

### Wrapper Components
- `.l-pad`: Consistent padding wrapper
- `.l-center-content`: Centers content with max-width
- `.l-cover`: Full-height centered layout
- `.l-frame`: Fixed aspect ratio container
- `.l-center`: Centering layout (horizontal, vertical, or both)

### Complex Layouts
- `.l-sidebar`: Sidebar layout with customizable position
- `.l-standard-page`: Header, main, footer page structure
- `.l-media`: Image and text layout
- `.l-tabs`: Flexible tabs layout


================================================
FILE: docs/layers/palette.md
================================================
# Palette Layer

The Palette layer defines comprehensive color palettes and scales for UI elements and data visualization. While the Theme layer provides semantic color roles, the Palette layer offers a complete range of color options for more specific use cases.

## Core Concept

The Palette layer creates systematic color scales with consistent steps in lightness and chroma, making it easy to represent hierarchies, states, and data. These color scales are implemented using OKLCH color space for perceptual uniformity and better color harmony.

## Color Scales

### Gray Scales

The framework provides multiple grayscale options with different undertones:

```css
/* Cool Gray Scale (default) */
--gray-0: oklch(var(--scale-l-0) min(var(--scale-c-1), var(--clamp-max-c-0)) var(--gray-h));
--gray-1: oklch(var(--scale-l-1) min(var(--scale-c-1), var(--clamp-max-c-0)) var(--gray-h));
--gray-2: oklch(var(--scale-l-2) var(--scale-c-1) var(--gray-h));
/* ... continuing to --gray-12 */

/* Neutral Gray Scale (no undertone) */
--neutral-0: oklch(var(--scale-l-0) 0 var(--neutral-h));
--neutral-1: oklch(var(--scale-l-1) 0 var(--neutral-h));
--neutral-2: oklch(var(--scale-l-2) 0 var(--neutral-h));
/* ... continuing to --neutral-12 */
```

### Brand Color Scales

Complete scales for brand colors with 13 steps (0-12):

```css
/* Accent Color Scale (Primary Brand) */
--accent-palette-0: oklch(var(--scale-l-0) min(var(--scale-c-1), var(--clamp-max-c-0)) var(--primary-h));
--accent-palette-1: oklch(var(--scale-l-1) min(var(--scale-c-2), var(--clamp-max-c-0)) var(--primary-h));
--accent-palette-2: oklch(var(--scale-l-2) var(--scale-c-3) var(--primary-h));
--accent-palette-3: oklch(var(--scale-l-3) var(--scale-c-4) var(--primary-h));
--accent-palette-4: oklch(var(--scale-l-4) var(--scale-c-5) var(--primary-h));
--accent-palette-5: oklch(var(--scale-l-5) var(--scale-c-6) var(--primary-h));
--accent-palette-6: oklch(var(--scale-l-6) var(--scale-c-7) var(--primary-h));
--accent-palette-7: oklch(var(--scale-l-7) var(--scale-c-8) var(--primary-h));
--accent-palette-8: oklch(var(--scale-l-8) var(--scale-c-9) var(--primary-h));
--accent-palette-9: oklch(var(--scale-l-9) var(--scale-c-8) var(--primary-h));
--accent-palette-10: oklch(var(--scale-l-10) var(--scale-c-7) var(--primary-h));
--accent-palette-11: oklch(var(--scale-l-11) var(--scale-c-6) var(--primary-h));
--accent-palette-12: oklch(var(--scale-l-12) min(var(--scale-c-5), var(--clamp-max-c-12)) var(--primary-h));
```

### Status Color Scales

Complete scales for status indicators with 13 steps (0-12):

```css
/* Success Palette */
--success-palette-0: oklch(var(--scale-l-0) min(var(--scale-c-1), var(--clamp-max-c-0)) var(--success-h));
--success-palette-1: oklch(var(--scale-l-1) min(var(--scale-c-2), var(--clamp-max-c-0)) var(--success-h));
--success-palette-2: oklch(var(--scale-l-2) var(--scale-c-3) var(--success-h));
/* ... continuing to --success-palette-12 */

/* Warning Palette */
--warning-palette-0: oklch(var(--scale-l-0) min(var(--scale-c-1), var(--clamp-max-c-0)) var(--warning-h));
--warning-palette-1: oklch(var(--scale-l-1) min(var(--scale-c-2), var(--clamp-max-c-0)) var(--warning-h));
--warning-palette-2: oklch(var(--scale-l-2) var(--scale-c-3) var(--warning-h));
/* ... continuing to --warning-palette-12 */

/* Error Palette */
--error-palette-0: oklch(var(--scale-l-0) min(var(--scale-c-1), var(--clamp-max-c-0)) var(--error-h));
--error-palette-1: oklch(var(--scale-l-1) min(var(--scale-c-2), var(--clamp-max-c-0)) var(--error-h));
--error-palette-2: oklch(var(--scale-l-2) var(--scale-c-3) var(--error-h));
/* ... continuing to --error-palette-12 */

/* Info Palette */
--info-palette-0: oklch(var(--scale-l-0) min(var(--scale-c-1), var(--clamp-max-c-0)) var(--info-h));
--info-palette-1: oklch(var(--scale-l-1) min(var(--scale-c-2), var(--clamp-max-c-0)) var(--info-h));
--info-palette-2: oklch(var(--scale-l-2) var(--scale-c-3) var(--info-h));
/* ... continuing to --info-palette-12 */
```

### Extended Color Palette

A comprehensive set of color scales for data visualization and UI design:

```css
/* Red */
--red-0: oklch(var(--scale-l-0) min(var(--scale-c-1), var(--clamp-max-c-0)) 0);
--red-1: oklch(var(--scale-l-1) min(var(--scale-c-2), var(--clamp-max-c-0)) 0);
--red-2: oklch(var(--scale-l-2) var(--scale-c-3) 0);
/* ... continuing to --red-12 */

/* Orange */
--orange-0: oklch(var(--scale-l-0) min(var(--scale-c-1), var(--clamp-max-c-0)) 30);
--orange-1: oklch(var(--scale-l-1) min(var(--scale-c-2), var(--clamp-max-c-0)) 30);
--orange-2: oklch(var(--scale-l-2) var(--scale-c-3) 30);
/* ... continuing to --orange-12 */

/* Yellow */
--yellow-0: oklch(var(--scale-l-0) min(var(--scale-c-1), var(--clamp-max-c-0)) 85);
--yellow-1: oklch(var(--scale-l-1) min(var(--scale-c-2), var(--clamp-max-c-0)) 85);
--yellow-2: oklch(var(--scale-l-2) var(--scale-c-3) 85);
/* ... continuing to --yellow-12 */

/* Green */
--green-0: oklch(var(--scale-l-0) min(var(--scale-c-1), var(--clamp-max-c-0)) 140);
--green-1: oklch(var(--scale-l-1) min(var(--scale-c-2), var(--clamp-max-c-0)) 140);
--green-2: oklch(var(--scale-l-2) var(--scale-c-3) 140);
/* ... continuing to --green-12 */

/* Cyan */
--cyan-0: oklch(var(--scale-l-0) min(var(--scale-c-1), var(--clamp-max-c-0)) 195);
--cyan-1: oklch(var(--scale-l-1) min(var(--scale-c-2), var(--clamp-max-c-0)) 195);
--cyan-2: oklch(var(--scale-l-2) var(--scale-c-3) 195);
/* ... continuing to --cyan-12 */

/* Blue */
--blue-0: oklch(var(--scale-l-0) min(var(--scale-c-1), var(--clamp-max-c-0)) 240);
--blue-1: oklch(var(--scale-l-1) min(var(--scale-c-2), var(--clamp-max-c-0)) 240);
--blue-2: oklch(var(--scale-l-2) var(--scale-c-3) 240);
/* ... continuing to --blue-12 */

/* Purple */
--purple-0: oklch(var(--scale-l-0) min(var(--scale-c-1), var(--clamp-max-c-0)) 280);
--purple-1: oklch(var(--scale-l-1) min(var(--scale-c-2), var(--clamp-max-c-0)) 280);
--purple-2: oklch(var(--scale-l-2) var(--scale-c-3) 280);
/* ... continuing to --purple-12 */

/* Pink */
--pink-0: oklch(var(--scale-l-0) min(var(--scale-c-1), var(--clamp-max-c-0)) 320);
--pink-1: oklch(var(--scale-l-1) min(var(--scale-c-2), var(--clamp-max-c-0)) 320);
--pink-2: oklch(var(--scale-l-2) var(--scale-c-3) 320);
/* ... continuing to --pink-12 */
```

### Specialized Color Scales

Additional color scales for specific use cases:

```css
/* Slate - Blue-gray variant */
--slate-0: oklch(var(--scale-l-0) min(var(--scale-c-1), var(--clamp-max-c-0)) 225);
--slate-1: oklch(var(--scale-l-1) min(var(--scale-c-1), var(--clamp-max-c-0)) 225);
--slate-2: oklch(var(--scale-l-2) var(--scale-c-1) 225);
/* ... continuing to --slate-12 */

/* Amber - Yellow-orange variant */
--amber-0: oklch(var(--scale-l-0) min(var(--scale-c-1), var(--clamp-max-c-0)) 65);
--amber-1: oklch(var(--scale-l-1) min(var(--scale-c-2), var(--clamp-max-c-0)) 65);
--amber-2: oklch(var(--scale-l-2) var(--scale-c-3) 65);
/* ... continuing to --amber-12 */

/* Teal - Blue-green variant */
--teal-0: oklch(var(--scale-l-0) min(var(--scale-c-1), var(--clamp-max-c-0)) 175);
--teal-1: oklch(var(--scale-l-1) min(var(--scale-c-2), var(--clamp-max-c-0)) 175);
--teal-2: oklch(var(--scale-l-2) var(--scale-c-3) 175);
/* ... continuing to --teal-12 */
```

## Color Palette Design

### Scale Structure

Each color scale follows a consistent pattern:

1. **Steps 0-2**: Very light shades (subtle backgrounds, highlights)
2. **Steps 3-5**: Light shades (backgrounds, subtle UI elements)
3. **Steps 6-8**: Mid-range shades (primary UI elements, borders)
4. **Steps 9-11**: Dark shades (text, prominent elements)
5. **Step 12**: Darkest shade (headings, emphasizing text)

### Color Scale Design Principles

The palette follows these key principles:

1. **Perceptual Uniformity**: Each step in the scale represents a similar perceptual difference
2. **Consistent Lightness**: The same lightness values are used across different hues
3. **Systematic Chroma**: Color intensity increases in the middle of the scale and decreases at the extremes
4. **Gamut Mapping**: Colors are clamped to ensure they're displayable on standard screens
5. **Accessibility**: The scale is designed to provide sufficient contrast options

### Special Considerations

#### Near-White and Near-Black Colors

The palette uses special handling for the extremes of the scale:

- **Near-White Colors (0-1)**: Limited chroma to prevent "off-white" appearances
- **Near-Black Colors (11-12)**: Limited chroma to prevent overly saturated dark colors

```css
/* Clamping chroma at the extremes */
--clamp-max-c-0: 0.03;  /* Max chroma for near-whites */
--clamp-max-c-12: 0.04; /* Max chroma for near-blacks */
```

#### Neutral vs. Tinted Grayscale

The framework provides both neutral and tinted grayscales:

- **Neutral**: True gray with zero chroma (pure grayscale)
- **Gray**: Slightly tinted grayscale with a cool undertone (default)

This allows more design flexibility while maintaining a cohesive look.

## Using the Palette Layer

### Direct Usage

The palette can be used directly for specific design needs:

```css
.data-visualization-element-1 {
  background-color: var(--blue-6);
}

.data-visualization-element-2 {
  background-color: var(--orange-6);
}

.data-visualization-element-3 {
  background-color: var(--green-6);
}
```

### In Data Visualizations

The palette is particularly useful for data visualizations:

```css
.chart-category-1 { background-color: var(--blue-6); }
.chart-category-2 { background-color: var(--green-6); }
.chart-category-3 { background-color: var(--purple-6); }
.chart-category-4 { background-color: var(--orange-6); }
.chart-category-5 { background-color: var(--red-6); }
```

### For Sequential Data

For sequential or gradient data, use steps from the same hue:

```css
.heat-map-level-1 { background-color: var(--red-2); }
.heat-map-level-2 { background-color: var(--red-4); }
.heat-map-level-3 { background-color: var(--red-6); }
.heat-map-level-4 { background-color: var(--red-8); }
.heat-map-level-5 { background-color: var(--red-10); }
```

### Creating Color Harmonies

The palette makes it easy to create color harmonies:

```css
/* Complementary Color Pair */
.primary { color: var(--blue-8); }
.complementary { color: var(--orange-8); }

/* Analogous Colors */
.primary { color: var(--blue-8); }
.analogous-1 { color: var(--cyan-8); }
.analogous-2 { color: var(--purple-8); }

/* Triadic Colors */
.triadic-1 { color: var(--blue-8); }
.triadic-2 { color: var(--red-8); }
.triadic-3 { color: var(--green-8); }
```

## Extending the Palette

### Adding Custom Colors

To add a new color to the palette:

```css
@layer palette {
  :root {
    /* Adding a custom "Rose" palette */
    --rose-h: 345; /* Define the hue */
    
    /* Generate the scale */
    --rose-0: oklch(var(--scale-l-0) min(var(--scale-c-1), var(--clamp-max-c-0)) var(--rose-h));
    --rose-1: oklch(var(--scale-l-1) min(var(--scale-c-2), var(--clamp-max-c-0)) var(--rose-h));
    --rose-2: oklch(var(--scale-l-2) var(--scale-c-3) var(--rose-h));
    /* ... and so on */
  }
}
```

### Creating Custom Palette Variants

For special needs, you can create palette variants:

```css
@layer palette {
  /* High saturation palette variant for vibrant designs */
  .high-saturation {
    --scale-c-3: 0.09;
    --scale-c-4: 0.12;
    --scale-c-5: 0.15;
    --scale-c-6: 0.18;
    --scale-c-7: 0.21;
    --scale-c-8: 0.24;
    --scale-c-9: 0.27;
  }
  
  /* Pastel palette variant for softer designs */
  .pastel {
    --scale-c-3: 0.04;
    --scale-c-4: 0.06;
    --scale-c-5: 0.08;
    --scale-c-6: 0.10;
    --scale-c-7: 0.12;
    --scale-c-8: 0.14;
    --scale-c-9: 0.16;
  }
}
```

## Complete Palette Reference

The palette includes these complete color scales (each with steps 0-12):

### Grayscale
- `--gray-{0-12}`: Cool gray (default)
- `--neutral-{0-12}`: True neutral gray

### Primary Palettes
- `--accent-palette-{0-12}`: Primary brand color scale
- `--success-palette-{0-12}`: Success color scale
- `--warning-palette-{0-12}`: Warning color scale
- `--error-palette-{0-12}`: Error color scale
- `--info-palette-{0-12}`: Info color scale

### Extended Color Palette
- `--red-{0-12}`: Red scale
- `--orange-{0-12}`: Orange scale
- `--amber-{0-12}`: Amber scale (yellow-orange)
- `--yellow-{0-12}`: Yellow scale
- `--lime-{0-12}`: Lime scale (yellow-green)
- `--green-{0-12}`: Green scale
- `--emerald-{0-12}`: Emerald scale (blue-green)
- `--teal-{0-12}`: Teal scale
- `--cyan-{0-12}`: Cyan scale
- `--sky-{0-12}`: Sky blue scale
- `--blue-{0-12}`: Blue scale
- `--indigo-{0-12}`: Indigo scale
- `--violet-{0-12}`: Violet scale
- `--purple-{0-12}`: Purple scale
- `--fuchsia-{0-12}`: Fuchsia scale
- `--pink-{0-12}`: Pink scale
- `--rose-{0-12}`: Rose scale (red-pink)

## Best Practices

1. **Use Semantic Variables**: For interface elements, prefer semantic variables from the Theme layer
2. **Consistent Step Usage**: Use the same step numbers across different hues for consistent visual weight
3. **Consider Accessibility**: Ensure sufficient contrast, especially for text elements
4. **Color Harmony**: Use related colors within the palette for harmony
5. **Dark Mode Considerations**: Test palette usage in both light and dark modes
6. **Data Visualization**: Reserve direct palette usage primarily for data visualization
7. **Document Custom Additions**: When extending the palette, document new colors and their intended use


================================================
FILE: docs/layers/reset.md
================================================
# Reset Layer

The Reset layer forms the foundation of our CSS framework, ensuring consistent rendering across browsers by neutralizing default browser styles.

## Core Concept

Unlike traditional CSS resets or normalizers, our Reset layer uses the `:where()` pseudo-class to apply styles with zero specificity. This innovative approach ensures that reset styles won't interfere with your custom styles, avoiding the specificity issues common in other CSS resets.

## Features

### Zero-Specificity Reset

All selectors are wrapped in `:where()` to ensure they have no specificity weight:

```css
:where(*, *::before, *::after) {
  margin: 0;
  padding: 0;
  box-sizing: border-box;
}
```

This means any style you define elsewhere will automatically override the reset styles without needing specificity hacks.

### Box Model Normalization

The Reset layer standardizes the box model using `box-sizing: border-box` for all elements, making layout calculations more intuitive and predictable.

### Typography Reset

Base typography is normalized to create a consistent foundation:

- Font sizes are set to use relative units
- Line heights are standardized
- Font families are inherited properly

### Form Element Normalization

Form elements are notoriously inconsistent across browsers:

- Input styles are normalized (borders, padding, etc.)
- Buttons are reset to have consistent behavior
- Select elements and other form controls are standardized

### List Reset

Lists (ul, ol) have their default styling removed:

- No default padding or margin
- No default list-style
- Consistent spacing behavior

### Table Reset

Tables are normalized for more predictable behavior:

- Border-collapse set to a consistent value
- Cell spacing and padding normalized
- Table layout optimized for common use cases

### Media Elements

Image, video, and other media elements are set to behave more predictably:

- `max-width: 100%` for responsive behavior by default
- Appropriate display properties
- Eliminated default margins and alignment issues

### Accessibility Considerations

The Reset layer is careful not to remove styles that aid accessibility:

- Focus states are preserved (not removed)
- Screen reader-only content handling is included
- Default interactive behaviors are maintained

## Using the Reset Layer

The Reset layer is meant to be used as-is without modification in most cases. It's the foundation that other layers build upon.

### When to Customize

You should rarely need to modify the Reset layer, but there are cases where you might:

- If you're supporting legacy browsers with specific normalization needs
- If you're working in a highly specialized domain with unique default style requirements
- If you have specific accessibility requirements that need foundational changes

### How to Extend

If you need to extend the Reset layer, make sure to:

1. Maintain the zero-specificity approach using `:where()`
2. Focus only on normalizing browser defaults, not adding new styles
3. Document your changes thoroughly, especially browser-specific fixes

```css
@layer reset {
  :where(your-new-selector) {
    /* Your reset properties */
  }
}
```

## Complete Reference

Here's what the Reset layer addresses:

### Box Model

- `box-sizing: border-box` for all elements
- Margin and padding reset to zero
- Border-width normalized

### Typography

- Font inheritance setup
- Line-height normalization
- Font-size baseline
- Text-decoration handling
- Vertical alignment fixes

### Lists

- List-style removal
- List spacing normalization
- Nested list behavior

### Tables

- Border-collapse setting
- Table layout properties
- Cell spacing and borders

### Forms

- Button appearance normalization
- Input styling consistency
- Form element inheritance properties
- Legend and fieldset fixes

### Media

- Image, video responsive defaults
- SVG normalization
- Media element alignment
- Max-width behavior

### Miscellaneous

- Hidden element handling
- Horizontal rule normalization
- Quote styling
- Code and pre element fixes

## Browser Support

The Reset layer is designed to work in all modern browsers, with careful consideration for:

- Chrome, Firefox, Safari, Edge (latest versions)
- Mobile browsers
- IE11 (with some polyfills)

For older browsers, additional normalization may be required through polyfills or supplementary CSS.


================================================
FILE: docs/layers/theme.md
================================================
# Theme Layer

The Theme layer assigns semantic meaning to the raw design tokens, creating a cohesive visual language for your application. It bridges the gap between abstract design tokens and their practical application in user interfaces.

## Core Concept

The Theme layer transforms abstract tokens into meaningful semantic variables that communicate their intended use. For example, instead of using a raw color token like `--scale-l-3` directly, you would use a semantic variable like `--text-default` that clearly communicates its purpose.

This layer is where theming capabilities come to life, enabling:
- Dark mode adaptation
- High contrast mode support
- Brand color customization
- Different visual themes

## Key Features

### Semantic Color System

The Theme layer defines semantic color roles that convey purpose rather than appearance:

```css
:root {
  /* Base Surface Colors */
  --base: oklch(var(--scale-l-0) var(--scale-c-1) var(--gray-h));
  --bedrock: oklch(var(--scale-l-1) var(--scale-c-2) var(--gray-h));
  
  /* Surface Colors - Progressive layers of UI */
  --surface-muted: oklch(var(--scale-l-1) var(--scale-c-1) var(--gray-h));
  --surface-subtle: oklch(var(--scale-l-2) var(--scale-c-1) var(--gray-h));
  --surface-default: oklch(var(--scale-l-3) var(--scale-c-2) var(--gray-h));
  --surface-overt: oklch(var(--scale-l-4) var(--scale-c-2) var(--gray-h));
  
  /* Text Colors - For content hierarchy */
  --text-muted: oklch(var(--scale-l-7) var(--scale-c-1) var(--gray-h));
  --text-subtle: oklch(var(--scale-l-8) var(--scale-c-2) var(--gray-h));
  --text-default: oklch(var(--scale-l-10) var(--scale-c-2) var(--gray-h));
  --text-overt: oklch(var(--scale-l-12) var(--scale-c-1) var(--gray-h));
  
  /* Outline Colors - For borders and separators */
  --outline-muted: oklch(var(--scale-l-4) var(--scale-c-1) var(--gray-h));
  --outline-subtle: oklch(var(--scale-l-5) var(--scale-c-2) var(--gray-h));
  --outline-default: oklch(var(--scale-l-6) var(--scale-c-2) var(--gray-h));
  --outline-overt: oklch(var(--scale-l-7) var(--scale-c-3) var(--gray-h));
}
```

### Brand Colors

The Theme layer defines key brand colors and their variants:

```css
:root {
  /* Primary Brand Color (Accent) */
  --accent: oklch(var(--scale-l-6) var(--scale-c-7) var(--primary-h));
  --accent-muted: oklch(var(--scale-l-6) var(--scale-c-3) var(--primary-h));
  --accent-subtle: oklch(var(--scale-l-3) var(--scale-c-1) var(--primary-h));
  --accent-overt: oklch(var(--scale-l-5) var(--scale-c-8) var(--primary-h));
  
  /* Secondary Brand Color */
  --secondary: oklch(var(--scale-l-6) var(--scale-c-7) calc(var(--primary-h) + 60));
  --secondary-muted: oklch(var(--scale-l-6) var(--scale-c-3) calc(var(--primary-h) + 60));
  --secondary-subtle: oklch(var(--scale-l-3) var(--scale-c-1) calc(var(--primary-h) + 60));
  --secondary-overt: oklch(var(--scale-l-5) var(--scale-c-8) calc(var(--primary-h) + 60));
  
  /* Tertiary Brand Color */
  --tertiary: oklch(var(--scale-l-6) var(--scale-c-7) calc(var(--primary-h) + 120));
  --tertiary-muted: oklch(var(--scale-l-6) var(--scale-c-3) calc(var(--primary-h) + 120));
  --tertiary-subtle: oklch(var(--scale-l-3) var(--scale-c-1) calc(var(--primary-h) + 120));
  --tertiary-overt: oklch(var(--scale-l-5) var(--scale-c-8) calc(var(--primary-h) + 120));
}
```

### Status Colors

The Theme layer defines colors for different status states:

```css
:root {
  /* Success */
  --success: oklch(var(--scale-l-5) var(--scale-c-7) var(--success-h));
  --text-success: oklch(var(--scale-l-5) var(--scale-c-8) var(--success-h));
  --outline-success: oklch(var(--scale-l-6) var(--scale-c-7) var(--success-h));
  --surface-success: oklch(var(--scale-l-2) var(--scale-c-1) var(--success-h));
  
  /* Warning */
  --warning: oklch(var(--scale-l-5) var(--scale-c-7) var(--warning-h));
  --text-warning: oklch(var(--scale-l-5) var(--scale-c-8) var(--warning-h));
  --outline-warning: oklch(var(--scale-l-6) var(--scale-c-7) var(--warning-h));
  --surface-warning: oklch(var(--scale-l-2) var(--scale-c-1) var(--warning-h));
  
  /* Error */
  --error: oklch(var(--scale-l-5) var(--scale-c-7) var(--error-h));
  --text-error: oklch(var(--scale-l-5) var(--scale-c-8) var(--error-h));
  --outline-error: oklch(var(--scale-l-6) var(--scale-c-7) var(--error-h));
  --surface-error: oklch(var(--scale-l-2) var(--scale-c-1) var(--error-h));
  
  /* Info */
  --info: oklch(var(--scale-l-5) var(--scale-c-7) var(--info-h));
  --text-info: oklch(var(--scale-l-5) var(--scale-c-8) var(--info-h));
  --outline-info: oklch(var(--scale-l-6) var(--scale-c-7) var(--info-h));
  --surface-info: oklch(var(--scale-l-2) var(--scale-c-1) var(--info-h));
}
```

### Interactive States

The Theme layer defines colors for different interactive states:

```css
:root {
  /* Link Colors */
  --text-link: var(--accent);
  --text-link-visited: oklch(var(--scale-l-5) var(--scale-c-6) calc(var(--primary-h) + 30));
  --text-link-hover: var(--accent-overt);
  --text-link-active: oklch(var(--scale-l-4) var(--scale-c-8) var(--primary-h));
  
  /* Focus States */
  --outline-focus: oklch(var(--scale-l-5) var(--scale-c-8) var(--primary-h));
  --outline-active: oklch(var(--scale-l-6) var(--scale-c-9) var(--primary-h));
  
  /* Highlight Colors */
  --text-highlight-subtle: oklch(var(--scale-l-5) var(--scale-c-7) var(--primary-h));
  --text-highlight-overt: oklch(var(--scale-l-4) var(--scale-c-8) var(--primary-h));
  --text-highlight-bg: oklch(var(--scale-l-2) var(--scale-c-3) var(--primary-h));
  --highlight-bg-muted: oklch(var(--scale-l-1) var(--scale-c-1) var(--primary-h));
  --highlight-bg-subtle: oklch(var(--scale-l-2) var(--scale-c-2) var(--primary-h));
  --highlight-bg-overt: oklch(var(--scale-l-3) var(--scale-c-3) var(--primary-h));
}
```

### Enhanced Focus State

The Theme layer includes comprehensive focus state variables for better accessibility:

```css
:root {
  /* Focus Ring Properties */
  --focus-ring-width: 2px;
  --focus-ring-offset: 2px;
  --focus-ring-color: var(--outline-focus);
  --focus-ring-style: solid;
  
  /* Input Focus States */
  --input-focus-ring-width: var(--focus-ring-width);
  --input-focus-ring-offset: 0px;
  --input-focus-bg: oklch(var(--scale-l-1) var(--scale-c-1) var(--primary-h));
}
```

### Dark Mode Support

The Theme layer includes a comprehensive dark mode transformation:

```css
@media (prefers-color-scheme: dark) {
  :root:not(.light) {
    /* Base Surface Colors - Dark Mode */
    --base: oklch(var(--scale-l-12) var(--scale-c-1) var(--gray-h));
    --bedrock: oklch(var(--scale-l-11) var(--scale-c-2) var(--gray-h));
    
    /* Surface Colors - Dark Mode */
    --surface-muted: oklch(var(--scale-l-11) var(--scale-c-1) var(--gray-h));
    --surface-subtle: oklch(var(--scale-l-10) var(--scale-c-1) var(--gray-h));
    --surface-default: oklch(var(--scale-l-9) var(--scale-c-2) var(--gray-h));
    --surface-overt: oklch(var(--scale-l-8) var(--scale-c-2) var(--gray-h));
    
    /* Text Colors - Dark Mode */
    --text-muted: oklch(var(--scale-l-5) var(--scale-c-1) var(--gray-h));
    --text-subtle: oklch(var(--scale-l-4) var(--scale-c-2) var(--gray-h));
    --text-default: oklch(var(--scale-l-2) var(--scale-c-2) var(--gray-h));
    --text-overt: oklch(var(--scale-l-0) var(--scale-c-1) var(--gray-h));
    
    /* Other dark mode adaptations... */
  }
}
```

### High Contrast Mode Support

The Theme layer includes adaptations for high contrast mode:

```css
@media (prefers-contrast: more) {
  :root {
    /* High contrast adaptations */
    --contrast-multiplier: 1.2;
    
    /* Increase contrast between elements */
    --text-default: oklch(calc(var(--scale-l-12) * var(--contrast-multiplier)) var(--scale-c-2) var(--gray-h));
    --text-muted: oklch(calc(var(--scale-l-8) * var(--contrast-multiplier)) var(--scale-c-3) var(--gray-h));
    
    /* Increase border contrast */
    --outline-default: oklch(calc(var(--scale-l-8) * var(--contrast-multiplier)) var(--scale-c-4) var(--gray-h));
    
    /* Strengthen focus indicators */
    --focus-ring-width: 3px;
    --focus-ring-style: dashed;
    
    /* Other high contrast adaptations... */
  }
}
```

## Using the Theme Layer

### In HTML/CSS

The Theme layer's semantic variables should be used throughout your application instead of raw tokens:

```css
.card {
  background-color: var(--surface-default);
  color: var(--text-default);
  border: 1px solid var(--outline-subtle);
  box-shadow: var(--shadow-sm);
}

.card__title {
  color: var(--text-overt);
  border-bottom: 1px solid var(--outline-muted);
}

.card__content {
  color: var(--text-default);
}

.card__action {
  color: var(--accent);
}
```

### Forcing Theme Modes

The Theme layer provides classes to force light or dark mode:

```html
<!-- Force light mode -->
<div class="light">
  This content will always use light mode styling
</div>

<!-- Force dark mode -->
<div class="dark">
  This content will always use dark mode styling
</div>
```

## Customizing the Theme

### Brand Color Customization

To customize brand colors, modify the hue variables:

```css
:root {
  --primary-h: 280; /* Purple accent */
  --secondary-h: 340; /* Complementary color automatically calculated */
}
```

### Creating a Custom Theme

To create a custom theme, extend the Theme layer:

```css
@layer theme {
  .theme-ocean {
    --primary-h: 200; /* Blue */
    --success-h: 170; /* Teal */
    --warning-h: 30; /* Orange */
    --error-h: 350; /* Red */
    --gray-h: 210; /* Cool gray */
    
    /* Customize surface colors for this theme */
    --surface-default: oklch(var(--scale-l-2) var(--scale-c-2) 220);
    
    /* Other theme customizations... */
  }
}
```

## Theme Layer Variables Reference

### Base Colors
- `--base`: The main background color of the application
- `--bedrock`: The darkest color of the theme, your "black"

### Surface Colors
- `--surface-muted`: The most subtle surface color
- `--surface-subtle`: A slightly more prominent surface
- `--surface-default`: The standard surface color
- `--surface-overt`: The most prominent surface color

### Text Colors
- `--text-muted`: The least important text
- `--text-subtle`: Secondary text
- `--text-default`: Primary text color
- `--text-overt`: The most prominent text
- `--text-link`: For hyperlinks
- `--text-success`/`--text-warning`/`--text-error`/`--text-info`: Status text

### Outline Colors
- `--outline-muted`: The subtlest border
- `--outline-subtle`: Secondary borders
- `--outline-default`: Primary border color
- `--outline-overt`: The most prominent border
- `--outline-focus`: For focus states
- `--outline-success`/`--outline-warning`/`--outline-error`/`--outline-info`: Status borders

### Brand Colors
- `--accent`: Primary brand color
- `--accent-muted`/`--accent-subtle`/`--accent-overt`: Accent variants
- `--secondary`: Secondary brand color
- `--tertiary`: Tertiary brand color

### Status Colors
- `--success`: For success states
- `--warning`: For warning states
- `--error`: For error states
- `--info`: For informational states

### Highlight Colors
- `--highlight-bg-muted`/`--highlight-bg-subtle`/`--highlight-bg-overt`: Background highlights
- `--text-highlight-subtle`/`--text-highlight-overt`: Text highlights

### Focus States
- `--focus-ring-width`: Width of focus outlines
- `--focus-ring-offset`: Space between element and focus outline
- `--focus-ring-color`: Color of focus outlines
- `--focus-ring-style`: Style of focus outlines

## Best Practices

1. **Use Semantic Variables**: Always use semantic variables from the Theme layer rather than raw tokens
2. **Respect Dark Mode**: Test your application in both light and dark modes
3. **Consider Accessibility**: Ensure sufficient contrast in all states
4. **Create Theme Variations**: Use cascade layers to extend the theme for variations

5. **Document Custom Themes**: When creating custom themes, document the color palette and usage guidelines



================================================
FILE: docs/layers/tokens.md
================================================
# Tokens Layer

The Tokens layer defines the fundamental design values of the system as CSS custom properties (variables). These tokens serve as the building blocks for the entire framework, creating a single source of truth for design values.

## Core Concept

Design tokens are named entities that store visual design attributes. They help create and maintain a scalable and consistent visual system for UI development. In our framework, tokens are implemented as CSS custom properties without any semantic meaning - they are raw values that get assigned semantic meaning in the Theme layer.

## Token Categories

### Color Tokens

Color tokens define the base colors used throughout the system:

```css
/* Base Color Hues */
--primary-h: 220;    /* Primary color hue (blue) */
--success-h: 160;    /* Success color hue (green) */
--warning-h: 35;     /* Warning color hue (amber) */
--error-h: 355;      /* Error color hue (red) */
--info-h: 200;       /* Info color hue (cyan) */
--gray-h: 220;       /* Gray color hue (cool gray) */
--neutral-h: 0;      /* Neutral gray hue (true gray) */

/* Base Lightness Scale */
--scale-l-0: 0.98;   /* Lightest value */
--scale-l-1: 0.95;
--scale-l-2: 0.90;
--scale-l-3: 0.85;
--scale-l-4: 0.78;
--scale-l-5: 0.70;
--scale-l-6: 0.60;
--scale-l-7: 0.50;
--scale-l-8: 0.40;
--scale-l-9: 0.32;
--scale-l-10: 0.25;
--scale-l-11: 0.18;
--scale-l-12: 0.10;  /* Darkest value */

/* Base Chroma Scale */
--scale-c-1: 0.02;
--scale-c-2: 0.04;
--scale-c-3: 0.06;
--scale-c-4: 0.08;
--scale-c-5: 0.10;
--scale-c-6: 0.12;
--scale-c-7: 0.14;
--scale-c-8: 0.16;
--scale-c-9: 0.18;
```

### Typography Tokens

Typography tokens define text styles and properties:

```css
/* Font Families */
--font-family-sans: ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, 'Helvetica Neue', Arial, sans-serif;
--font-family-serif: ui-serif, Georgia, Cambria, 'Times New Roman', Times, serif;
--font-family-mono: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, 'Liberation Mono', 'Courier New', monospace;

/* Font Sizes */
--font-size-xs: 0.75rem;
--font-size-sm: 0.875rem;
--font-size-base: 1rem;
--font-size-md: 1.125rem;
--font-size-lg: 1.25rem;
--font-size-xl: 1.5rem;
--font-size-2xl: 1.75rem;
--font-size-3xl: 2rem;
--font-size-4xl: 2.5rem;

/* Font Weights */
--font-weight-thin: 100;
--font-weight-extra-light: 200;
--font-weight-light: 300;
--font-weight-normal: 400;
--font-weight-medium: 500;
--font-weight-semibold: 600;
--font-weight-bold: 700;
--font-weight-extra-bold: 800;
--font-weight-black: 900;

/* Line Heights */
--line-height-none: 1;
--line-height-tight: 1.25;
--line-height-snug: 1.375;
--line-height-normal: 1.5;
--line-height-relaxed: 1.625;
--line-height-loose: 2;

/* Letter Spacing */
--letter-spacing-tighter: -0.05em;
--letter-spacing-tight: -0.025em;
--letter-spacing-normal: 0em;
--letter-spacing-wide: 0.025em;
--letter-spacing-wider: 0.05em;
--letter-spacing-widest: 0.1em;
```

### Spacing Tokens

Spacing tokens define the whitespace system:

```css
/* Spacing Scale */
--space-0: 0;
--space-px: 1px;
--space-xs: 0.25rem;  /* 4px */
--space-sm: 0.5rem;   /* 8px */
--space-md: 1rem;     /* 16px */
--space-lg: 1.5rem;   /* 24px */
--space-xl: 2rem;     /* 32px */
--space-2xl: 3rem;    /* 48px */
--space-3xl: 4rem;    /* 64px */
```

### Border Tokens

Border tokens define border styles, widths, and radii:

```css
/* Border Widths */
--border-width-none: 0;
--border-width-thin: 1px;
--border-width: 2px;
--border-width-thick: 3px;

/* Border Radii */
--radius-none: 0;
--radius-sm: 0.125rem;  /* 2px */
--radius-md: 0.25rem;   /* 4px */
--radius-lg: 0.5rem;    /* 8px */
--radius-xl: 1rem;      /* 16px */
--radius-full: 9999px;
```

### Shadow Tokens

Shadow tokens define the elevation system:

```css
/* Shadow Color Base using HSL format for easier adjustments */
--shadow-color-base: 220 10% 10%;
--shadow-color-dark: 220 20% 90%;

/* Light Mode Shadows */
--shadow-sm: 0 1px 2px oklch(from hsl(var(--shadow-color-base)) l c h / 7%),
             0 1px 1px oklch(from hsl(var(--shadow-color-base)) l c h / 4%);

--shadow-md: 0 4px 6px oklch(from hsl(var(--shadow-color-base)) l c h / 7%),
             0 2px 4px oklch(from hsl(var(--shadow-color-base)) l c h / 4%);

--shadow-lg: 0 10px 15px oklch(from hsl(var(--shadow-color-base)) l c h / 8%),
             0 4px 6px oklch(from hsl(var(--shadow-color-base)) l c h / 5%);

--shadow-xl: 0 20px 25px oklch(from hsl(var(--shadow-color-base)) l c h / 10%),
             0 8px 10px oklch(from hsl(var(--shadow-color-base)) l c h / 6%);

--shadow-inner: inset 0 2px 4px oklch(from hsl(var(--shadow-color-base)) l c h / 6%);
```

### Z-Index Tokens

Z-index tokens define the stacking order:

```css
--z-index-0: 0;
--z-index-10: 10;
--z-index-20: 20;
--z-index-30: 30;
--z-index-40: 40;
--z-index-50: 50;
--z-index-auto: auto;
```

### Animation Tokens

Animation tokens define timing and easing:

```css
/* Animation Timing */
--animation-duration-fast: 150ms;
--animation-duration-normal: 300ms;
--animation-duration-slow: 500ms;

/* Easing Functions */
--ease-linear: linear;
--ease-in: cubic-bezier(0.4, 0, 1, 1);
--ease-out: cubic-bezier(0, 0, 0.2, 1);
--ease-in-out: cubic-bezier(0.4, 0, 0.2, 1);
```

### Opacity Tokens

Opacity tokens define transparency levels:

```css
--alpha-0: 0;
--alpha-1: 0.05;
--alpha-2: 0.1;
--alpha-3: 0.2;
--alpha-4: 0.4;
--alpha-5: 0.6;
--alpha-6: 0.75;
--alpha-7: 0.8;
--alpha-8: 0.9;
--alpha-9: 0.95;
--alpha-10: 1;
```

### Container Query Breakpoints

Tokens for container query breakpoints:

```css
--cq-bp-xs: 20em;  /* 320px */
--cq-bp-sm: 30em;  /* 480px */
--cq-bp-md: 45em;  /* 720px */
--cq-bp-lg: 60em;  /* 960px */
--cq-bp-xl: 75em;  /* 1200px */
```

## Advanced Token Features

### Token Registration with @property

Some tokens use the `@property` CSS at-rule to define proper inheritance and interpolation behavior:

```css
@property --accent-h {
  syntax: "<number>";
  initial-value: 220;
  inherits: true;
}
```

This ensures that tokens are interpolated correctly during animations and transitions, particularly important for color tokens.

### Color Palette Calculations

The Tokens layer includes base calculations for systematic color palette generation:

```css
/* Delta Values for systematic modifications */
--l-delta-1-up: 0.05;
--l-delta-2-up: 0.10;
--l-delta-3-up: 0.15;
--l-delta-1-down: -0.05;
--l-delta-2-down: -0.10;
--l-delta-3-down: -0.15;

/* Chroma Constraints */
--clamp-max-c-0: 0.03;  /* Max chroma for near-whites */
--clamp-max-c-12: 0.04; /* Max chroma for near-blacks */
```

## Using Tokens

Tokens should never be used directly in your HTML. Instead:

1. Use them to build semantic variables in the Theme layer
2. Use them in custom component definitions
3. Reference them in utility classes

For example, instead of:

```html
<!-- DON'T do this -->
<div style="padding: var(--space-md); color: oklch(var(--scale-l-12) var(--scale-c-9) var(--primary-h));">
  Content
</div>
```

Do this:

```html
<!-- DO this instead -->
<div class="p-md text-default bg-surface-subtle">
  Content
</div>
```

## Extending Tokens

To add new tokens to the system:

1. Add them to the Tokens layer
2. Follow the existing naming conventions
3. Create corresponding semantic variables in the Theme layer

Example:

```css
@layer tokens {
  :root {
    /* Custom icon size tokens */
    --icon-size-sm: 1rem;
    --icon-size-md: 1.5rem;
    --icon-size-lg: 2rem;
  }
}

@layer theme {
  :root {
    /* Semantic usage of the tokens */
    --icon-navigation: var(--icon-size-md);
    --icon-button: var(--icon-size-sm);
    --icon-hero: var(--icon-size-lg);
  }
}
```

## Design Token Philosophy

Our tokens follow these principles:

1. **Abstraction**: Tokens are abstracted from their application
2. **Consistency**: Tokens provide a consistent system of values
3. **Scalability**: Tokens can be extended without breaking existing patterns
4. **Clarity**: Token names clearly communicate their purpose and value
5. **Composability**: Tokens can be combined to create more complex values

By adhering to these principles, the token system enables a consistent, maintainable, and scalable design language.


================================================
FILE: docs/layers/utilities.md
================================================
# Utilities Layer

The Utilities layer provides single-purpose utility classes for quickly applying specific styles directly in your HTML. These utility classes form a powerful system for rapid development, fine-tuning designs, and creating consistent interfaces without writing custom CSS.

## Core Concept

Utility classes follow a functional CSS approach, where each class does one thing and does it well. This creates a highly composable system where complex designs can be built by combining multiple small, focused classes.

Unlike the Components layer (which provides pre-designed patterns), the Utilities layer provides atomic building blocks that can be combined in countless ways to implement custom designs without writing new CSS.

## Key Features

### Design Token Mapping

Utility classes directly map to the design tokens defined in the Tokens layer, ensuring consistency with the design system:

```css
/* Spacing utility classes map to spacing tokens */
.m-0 { margin: var(--space-0); }
.m-xs { margin: var(--space-xs); }
.m-sm { margin: var(--space-sm); }
.m-md { margin: var(--space-md); }
/* ... */

/* Typography utility classes map to typography tokens */
.text-xs { font-size: var(--font-size-xs); }
.text-sm { font-size: var(--font-size-sm); }
.text-base { font-size: var(--font-size-base); }
.text-lg { font-size: var(--font-size-lg); }
/* ... */
```

### High Specificity

The Utilities layer has the highest specificity in the cascade (except for Layouts), allowing utility classes to override styles from the Components and Defaults layers:

```css
@layer reset, tokens, engine, theme, palette, defaults, components, utilities, layouts;
```

This means you can easily adjust component styles without having to write additional CSS.

### Consistent Naming Convention

Utility classes follow a consistent naming convention:

- `property-value` format (e.g., `text-lg`, `m-md`)
- Abbreviated property names for common properties (e.g., `bg` for background-color)
- Full property names for less common properties (e.g., `opacity`)
- Direction modifiers for spacing and positioning (e.g., `mt` for margin-top)

## Utility Categories

### Color Utilities

#### Background Colors

Theme role background colors:

```css
.bg-base { background-color: var(--base); }
.bg-bedrock { background-color: var(--bedrock); }
.bg-surface-muted { background-color: var(--surface-muted); }
.bg-surface-subtle { background-color: var(--surface-subtle); }
.bg-surface-default { background-color: var(--surface-default); }
.bg-surface-overt { background-color: var(--surface-overt); }
.bg-accent { background-color: var(--accent); }
.bg-secondary { background-color: var(--secondary); }
.bg-tertiary { background-color: var(--tertiary); }
.bg-success { background-color: var(--success); }
.bg-warning { background-color: var(--warning); }
.bg-error { background-color: var(--error); }
.bg-info { background-color: var(--info); }
.bg-transparent { background-color: transparent; }
```

Palette scale background colors:

```css
.bg-gray-0 { background-color: var(--gray-0); }
.bg-gray-1 { background-color: var(--gray-1); }
/* ... through .bg-gray-12 */

.bg-blue-0 { background-color: var(--blue-0); }
/* ... */
.bg-blue-12 { background-color: var(--blue-12); }

/* ... similar classes for all color scales */
```

#### Text Colors

Theme role text colors:

```css
.text-muted { color: var(--text-muted); }
.text-subtle { color: var(--text-subtle); }
.text-default { color: var(--text-default); }
.text-overt { color: var(--text-overt); }
.text-link { color: var(--text-link); }
.text-success { color: var(--text-success); }
.text-warning { color: var(--text-warning); }
.text-error { color: var(--text-error); }
.text-info { color: var(--text-info); }
.text-inherit { color: inherit; }
```

Contrast text colors:

```css
.text-contrast-on-base { --bg: var(--base); color:     var(--auto-contrast-text, oklch(
  from var(--bg, currentColor)
  clamp(0.1, (var(--l-threshold, 0.65) / l - 1) * 999, 0.98)
  min(c, var(--c-threshold, 0.08))
  h
)); }
.text-contrast-on-accent { --bg: var(--accent); color:     var(--auto-contrast-text, oklch(
  from var(--bg, currentColor)
  clamp(0.1, (var(--l-threshold, 0.65) / l - 1) * 999, 0.98)
  min(c, var(--c-threshold, 0.08))
  h
)); }
/* ... similar classes for other backgrounds */
```

Palette scale text colors:

```css
.text-gray-0 { color: var(--gray-0); }
.text-gray-1 { color: var(--gray-1); }
/* ... through .text-gray-12 */

/* ... similar classes for all color scales */
```

#### Border Colors

Theme role border colors:

```css
.border-outline-muted { border-color: var(--outline-muted); }
.border-outline-subtle { border-color: var(--outline-subtle); }
.border-outline-default { border-color: var(--outline-default); }
.border-outline-overt { border-color: var(--outline-overt); }
.border-accent { border-color: var(--accent); }
.border-success { border-color: var(--outline-success); }
.border-warning { border-color: var(--outline-warning); }
.border-error { border-color: var(--outline-error); }
.border-info { border-color: var(--outline-info); }
.border-transparent { border-color: transparent; }
```

### Spacing Utilities

#### Margin

```css
/* All sides */
.m-0 { margin: var(--space-0); }
.m-px { margin: var(--space-px); }
.m-xs { margin: var(--space-xs); }
.m-sm { margin: var(--space-sm); }
.m-md { margin: var(--space-md); }
.m-lg { margin: var(--space-lg); }
.m-xl { margin: var(--space-xl); }
.m-2xl { margin: var(--space-2xl); }
.m-3xl { margin: var(--space-3xl); }
.m-auto { margin: auto; }

/* Horizontal (x-axis) */
.mx-0 { margin-left: var(--space-0); margin-right: var(--space-0); }
.mx-px { margin-left: var(--space-px); margin-right: var(--space-px); }
/* ... through .mx-3xl */
.mx-auto { margin-left: auto; margin-right: auto; }

/* Vertical (y-axis) */
.my-0 { margin-top: var(--space-0); margin-bottom: var(--space-0); }
.my-px { margin-top: var(--space-px); margin-bottom: var(--space-px); }
/* ... through .my-3xl */
.my-auto { margin-top: auto; margin-bottom: auto; }

/* Individual sides (top, right, bottom, left) also available */
```

#### Padding

```css
/* All sides */
.p-0 { padding: var(--space-0); }
.p-px { padding: var(--space-px); }
.p-xs { padding: var(--space-xs); }
.p-sm { padding: var(--space-sm); }
.p-md { padding: var(--space-md); }
.p-lg { padding: var(--space-lg); }
.p-xl { padding: var(--space-xl); }
.p-2xl { padding: var(--space-2xl); }
.p-3xl { padding: var(--space-3xl); }

/* Horizontal (x-axis) */
.px-0 { padding-left: var(--space-0); padding-right: var(--space-0); }
.px-px { padding-left: var(--space-px); padding-right: var(--space-px); }
/* ... through .px-3xl */

/* Vertical (y-axis) */
.py-0 { padding-top: var(--space-0); padding-bottom: var(--space-0); }
.py-px { padding-top: var(--space-px); padding-bottom: var(--space-px); }
/* ... through .py-3xl */

/* Individual sides (top, right, bottom, left) also available */
```

#### Gap

```css
.gap-0 { gap: var(--space-0); }
.gap-px { gap: var(--space-px); }
.gap-xs { gap: var(--space-xs); }
.gap-sm { gap: var(--space-sm); }
.gap-md { gap: var(--space-md); }
.gap-lg { gap: var(--space-lg); }
.gap-xl { gap: var(--space-xl); }
.gap-2xl { gap: var(--space-2xl); }
.gap-3xl { gap: var(--space-3xl); }
```

### Typography Utilities

#### Font Family

```css
.font-sans { font-family: var(--font-family-sans); }
.font-serif { font-family: var(--font-family-serif); }
.font-mono { font-family: var(--font-family-mono); }
```

#### Font Size

```css
.text-xs { font-size: var(--font-size-xs); }
.text-sm { font-size: var(--font-size-sm); }
.text-base { font-size: var(--font-size-base); }
.text-md { font-size: var(--font-size-md); }
.text-lg { font-size: var(--font-size-lg); }
.text-xl { font-size: var(--font-size-xl); }
.text-2xl { font-size: var(--font-size-2xl); }
.text-3xl { font-size: var(--font-size-3xl); }
.text-4xl { font-size: var(--font-size-4xl); }
```

#### Font Weight

```css
.font-thin { font-weight: var(--font-weight-thin); }
.font-extra-light { font-weight: var(--font-weight-extra-light); }
.font-light { font-weight: var(--font-weight-light); }
.font-normal { font-weight: var(--font-weight-normal); }
.font-medium { font-weight: var(--font-weight-medium); }
.font-semibold { font-weight: var(--font-weight-semibold); }
.font-bold { font-weight: var(--font-weight-bold); }
.font-extra-bold { font-weight: var(--font-weight-extra-bold); }
.font-black { font-weight: var(--font-weight-black); }
```

#### Line Height

```css
.leading-none { line-height: var(--line-height-none); }
.leading-tight { line-height: var(--line-height-tight); }
.leading-snug { line-height: var(--line-height-snug); }
.leading-normal { line-height: var(--line-height-normal); }
.leading-relaxed { line-height: var(--line-height-relaxed); }
.leading-loose { line-height: var(--line-height-loose); }
```

#### Letter Spacing

```css
.tracking-tighter { letter-spacing: var(--letter-spacing-tighter); }
.tracking-tight { letter-spacing: var(--letter-spacing-tight); }
.tracking-normal { letter-spacing: var(--letter-spacing-normal); }
.tracking-wide { letter-spacing: var(--letter-spacing-wide); }
.tracking-wider { letter-spacing: var(--letter-spacing-wider); }
.tracking-widest { letter-spacing: var(--letter-spacing-widest); }
```

#### Text Alignment

```css
.text-left { text-align: left; }
.text-center { text-align: center; }
.text-right { text-align: right; }
.text-justify { text-align: justify; }
```

### Border Utilities

#### Border Width

```css
.border { border-width: var(--border-width); }
.border-thin { border-width: var(--border-width-thin); }
.border-thick { border-width: var(--border-width-thick); }
.border-none { border-width: 0; }
```

#### Border Radius

```css
.rounded-none { border-radius: 0; }
.rounded-sm { border-radius: var(--radius-sm); }
.rounded-md { border-radius: var(--radius-md); }
.rounded-lg { border-radius: var(--radius-lg); }
.rounded-xl { border-radius: var(--radius-xl); }
.rounded-full { border-radius: var(--radius-full); }
```

### Shadow Utilities

```css
.shadow-none { box-shadow: none; }
.shadow-sm { box-shadow: var(--shadow-sm); }
.shadow-md { box-shadow: var(--shadow-md); }
.shadow-lg { box-shadow: var(--shadow-lg); }
.shadow-xl { box-shadow: var(--shadow-xl); }
.shadow-inner { box-shadow: var(--shadow-inner); }
```

### Position Utilities

```css
.static { position: static; }
.fixed { position: fixed; }
.absolute { position: absolute; }
.relative { position: relative; }
.sticky { position: sticky; }
```

### Z-Index Utilities

```css
.z-0 { z-index: var(--z-index-0); }
.z-10 { z-index: var(--z-index-10); }
.z-20 { z-index: var(--z-index-20); }
.z-30 { z-index: var(--z-index-30); }
.z-40 { z-index: var(--z-index-40); }
.z-50 { z-index: var(--z-index-50); }
.z-auto { z-index: var(--z-index-auto); }
```

### Display Utilities

```css
.block { display: block; }
.inline-block { display: inline-block; }
.inline { display: inline; }
.flex { display: flex; }
.inline-flex { display: inline-flex; }
.grid { display: grid; }
.inline-grid { display: inline-grid; }
.hidden { display: none; }
```

### Flex Utilities

```css
.flex-row { flex-direction: row; }
.flex-row-reverse { flex-direction: row-reverse; }
.flex-col { flex-direction: column; }
.flex-col-reverse { flex-direction: column-reverse; }
.flex-wrap { flex-wrap: wrap; }
.flex-nowrap { flex-wrap: nowrap; }
.flex-wrap-reverse { flex-wrap: wrap-reverse; }
.flex-1 { flex: var(--flex-1); }
.flex-auto { flex: var(--flex-auto); }
.flex-initial { flex: var(--flex-initial); }
.flex-none { flex: var(--flex-none); }
```

### Grid Utilities

```css
.grid-cols-1 { grid-template-columns: repeat(1, minmax(0, 1fr)); }
.grid-cols-2 { grid-template-columns: repeat(2, minmax(0, 1fr)); }
.grid-cols-3 { grid-template-columns: repeat(3, minmax(0, 1fr)); }
.grid-cols-4 { grid-template-columns: repeat(4, minmax(0, 1fr)); }
.grid-cols-6 { grid-template-columns: repeat(6, minmax(0, 1fr)); }
.grid-cols-12 { grid-template-columns: repeat(12, minmax(0, 1fr)); }
```

### Width and Height Utilities

```css
.w-auto { width: auto; }
.w-full { width: 100%; }
.w-screen { width: 100vw; }
.w-min { width: min-content; }
.w-max { width: max-content; }
.w-fit { width: fit-content; }
.w-1\/2 { width: 50%; }
.w-1\/3 { width: 33.333333%; }
.w-2\/3 { width: 66.666667%; }
.w-1\/4 { width: 25%; }
.w-3\/4 { width: 75%; }

.h-auto { height: auto; }
.h-full { height: 100%; }
.h-screen { height: 100vh; }
.h-min { height: min-content; }
.h-max { height: max-content; }
.h-fit { height: fit-content; }
.h-1\/2 { height: 50%; }
.h-1\/3 { height: 33.333333%; }
.h-2\/3 { height: 66.666667%; }
```

### Opacity Utilities

```css
.opacity-0 { opacity: var(--alpha-0); }
.opacity-5 { opacity: var(--alpha-1); }
.opacity-10 { opacity: var(--alpha-2); }
.opacity-20 { opacity: var(--alpha-3); }
.opacity-40 { opacity: var(--alpha-4); }
.opacity-60 { opacity: var(--alpha-5); }
.opacity-75 { opacity: var(--alpha-6); }
.opacity-80 { opacity: var(--alpha-7); }
.opacity-90 { opacity: var(--alpha-8); }
.opacity-95 { opacity: var(--alpha-9); }
.opacity-100 { opacity: var(--alpha-10); }
```

### Overflow Utilities

```css
.overflow-auto { overflow: auto; }
.overflow-hidden { overflow: hidden; }
.overflow-visible { overflow: visible; }
.overflow-scroll { overflow: scroll; }
.overflow-x-auto { overflow-x: auto; }
.overflow-y-auto { overflow-y: auto; }
.overflow-x-hidden { overflow-x: hidden; }
.overflow-y-hidden { overflow-y: hidden; }
```

### Interactivity Utilities

```css
.cursor-auto { cursor: auto; }
.cursor-default { cursor: default; }
.cursor-pointer { cursor: pointer; }
.cursor-wait { cursor: wait; }
.cursor-text { cursor: text; }
.cursor-move { cursor: move; }
.cursor-not-allowed { cursor: not-allowed; }

.pointer-events-none { pointer-events: none; }
.pointer-events-auto { pointer-events: auto; }

.select-none { user-select: none; }
.select-text { user-select: text; }
.select-all { user-select: all; }
.select-auto { user-select: auto; }
```

### Accessibility Utilities

```css
.sr-only {
  position: absolute;
  width: 1px;
  height: 1px;
  padding: 0;
  margin: -1px;
  overflow: hidden;
  clip: rect(0, 0, 0, 0);
  white-space: nowrap;
  border-width: 0;
}

.not-sr-only {
  position: static;
  width: auto;
  height: auto;
  padding: 0;
  margin: 0;
  overflow: visible;
  clip: auto;
  white-space: normal;
}

.focus-visible-outline:focus-visible {
  outline: var(--focus-ring-width) var(--focus-ring-style) var(--focus-ring-color);
  outline-offset: var(--focus-ring-offset);
}
```

### Button Style Utilities

For use with the button component:

```css
/* Filled Buttons */
.button-filled-accent { background-color: var(--accent); --bg: var(--accent); color:     var(--auto-contrast-text, oklch(
  from var(--bg, currentColor)
  clamp(0.1, (var(--l-threshold, 0.65) / l - 1) * 999, 0.98)
  min(c, var(--c-threshold, 0.08))
  h
)); border-color: transparent; }
.button-filled-secondary { background-color: var(--secondary); --bg: var(--secondary); color:     var(--auto-contrast-text, oklch(
  from var(--bg, currentColor)
  clamp(0.1, (var(--l-threshold, 0.65) / l - 1) * 999, 0.98)
  min(c, var(--c-threshold, 0.08))
  h
)); border-color: transparent; }
.button-filled-tertiary { background-color: var(--tertiary); --bg: var(--tertiary); color:     var(--auto-contrast-text, oklch(
  from var(--bg, currentColor)
  clamp(0.1, (var(--l-threshold, 0.65) / l - 1) * 999, 0.98)
  min(c, var(--c-threshold, 0.08))
  h
)); border-color: transparent; }
.button-filled-success { background-color: var(--success); --bg: var(--success); color:     var(--auto-contrast-text, oklch(
  from var(--bg, currentColor)
  clamp(0.1, (var(--l-threshold, 0.65) / l - 1) * 999, 0.98)
  min(c, var(--c-threshold, 0.08))
  h
)); border-color: transparent; }
.button-filled-warning { background-color: var(--warning); --bg: var(--warning); color:     var(--auto-contrast-text, oklch(
  from var(--bg, currentColor)
  clamp(0.1, (var(--l-threshold, 0.65) / l - 1) * 999, 0.98)
  min(c, var(--c-threshold, 0.08))
  h
)); border-color: transparent; }
.button-filled-error { background-color: var(--error); --bg: var(--error); color:     var(--auto-contrast-text, oklch(
  from var(--bg, currentColor)
  clamp(0.1, (var(--l-threshold, 0.65) / l - 1) * 999, 0.98)
  min(c, var(--c-threshold, 0.08))
  h
)); border-color: transparent; }
.button-filled-info { background-color: var(--info); --bg: var(--info); color:     var(--auto-contrast-text, oklch(
  from var(--bg, currentColor)
  clamp(0.1, (var(--l-threshold, 0.65) / l - 1) * 999, 0.98)
  min(c, var(--c-threshold, 0.08))
  h
)); border-color: transparent; }
.button-filled-gray { background-color: var(--surface-overt); --bg: var(--surface-overt); color:     var(--auto-contrast-text, oklch(
  from var(--bg, currentColor)
  clamp(0.1, (var(--l-threshold, 0.65) / l - 1) * 999, 0.98)
  min(c, var(--c-threshold, 0.08))
  h
)); border-color: transparent; }

/* Outline Buttons */
.button-outline-accent { color: var(--accent); border-color: var(--accent-subtle); background-color: transparent; }
.button-outline-secondary { color: var(--secondary); border-color: var(--secondary-subtle); background-color: transparent; }
.button-outline-tertiary { color: var(--tertiary); border-color: var(--tertiary-subtle); background-color: transparent; }
.button-outline-success { color: var(--success); border-color: var(--outline-success); background-color: transparent; }
.button-outline-warning { color: var(--warning); border-color: var(--outline-warning); background-color: transparent; }
.button-outline-error { color: var(--error); border-color: var(--outline-error); background-color: transparent; }
.button-outline-info { color: var(--info); border-color: var(--outline-info); background-color: transparent; }
.button-outline-gray { color: var(--text-subtle); border-color: var(--outline-default); background-color: transparent; }

/* Text Buttons */
.button-text-accent { color: var(--accent); background-color: transparent; border-color: transparent;}
.button-text-secondary { color: var(--secondary); background-color: transparent; border-color: transparent;}
.button-text-tertiary { color: var(--tertiary); background-color: transparent; border-color: transparent;}
.button-text-success { color: var(--success); background-color: transparent; border-color: transparent;}
.button-text-warning { color: var(--warning); background-color: transparent; border-color: transparent;}
.button-text-error { color: var(--error); background-color: transparent; border-color: transparent;}
.button-text-info { color: var(--info); background-color: transparent; border-color: transparent;}
.button-text-gray { color: var(--text-subtle); background-color: transparent; border-color: transparent;}
```

## Using the Utilities Layer

### Basic Usage

Utility classes are applied directly in your HTML:

```html
<div class="bg-surface-default p-md rounded-md shadow-md">
  <h2 class="text-xl font-bold text-default mb-sm">Card Title</h2>
  <p class="text-subtle mb-md">Card description goes here.</p>
  <button class="button button-filled-accent">Action</button>
</div>
```

### Combining Utilities

The power of utilities comes from combining them:

```html
<!-- A responsive card with hover effect -->
<div class="bg-surface-default p-sm p-md rounded-md shadow-sm hover:shadow-lg transition">
  <div class="flex items-center gap-sm mb-md">
    <div class="rounded-full bg-accent w-12 h-12 flex items-center justify-center text-white font-bold">A</div>
    <div>
      <h3 class="text-lg font-semibold text-default">Card Title</h3>
      <p class="text-sm text-subtle">Subtitle or metadata</p>
    </div>
  </div>
  <p class="text-default mb-md">This is the card content with a <a href="#" class="text-link">link</a>.</p>
  <div class="flex justify-end gap-sm">
    <button class="button button-text-subtle">Cancel</button>
    <button class="button button-filled-accent">Action</button>
  </div>
</div>
```

### With Components

Utility classes work well with components to customize them for specific contexts:

```html
<div class="card mb-lg shadow-lg">
  <div class="card__header bg-accent-subtle">
    <h2 class="card__title text-accent">Custom Header</h2>
  </div>
  <div class="card__body p-lg">
    <p class="text-default mb-md">Card content with custom padding.</p>
    <div class="flex flex-col gap-md">
      <input type="text" class="form-input border-accent-subtle" placeholder="Enter value">
      <textarea class="form-input h-24" placeholder="Additional details"></textarea>
    </div>
  </div>
  <div class="card__footer flex justify-between">
    <button class="button button-text-subtle">Cancel</button>
    <button class="button button-filled-accent">Submit</button>
  </div>
</div>
```

## Extending the Utilities Layer

### Adding New Utilities

To add new utility classes, extend the Utilities layer:

```css
@layer utilities {
  /* Adding new utilities */
  .rotate-45 { transform: rotate(45deg); }
  .rotate-90 { transform: rotate(90deg); }
  .rotate-180 { transform: rotate(180deg); }
  
  .scale-75 { transform: scale(0.75); }
  .scale-90 { transform: scale(0.9); }
  .scale-110 { transform: scale(1.1); }
  .scale-125 { transform: scale(1.25); }
  
  .transition-transform { transition-property: transform; }
  .transition-colors { transition-property: color, background-color, border-color; }
  .transition-opacity { transition-property: opacity; }
  .transition-all { transition-property: all; }
  
  .duration-100 { transition-duration: 100ms; }
  .duration-200 { transition-duration: 200ms; }
  .duration-300 { transition-duration: 300ms; }
  .duration-500 { transition-duration: 500ms; }
}
```

### Creating Utility Variants

For more complex scenarios, create utility variants:

```css
@layer utilities {
  /* Hover variants */
  .hover\:bg-accent:hover { background-color: var(--accent); }
  .hover\:text-accent:hover { color: var(--accent); }
  .hover\:scale-105:hover { transform: scale(1.05); }
  
  /* Focus variants */
  .focus\:border-accent:focus { border-color: var(--accent); }
  .focus\:outline-none:focus { outline: none; }
  
  /* Active variants */
  .active\:bg-accent-overt:active { background-color: var(--accent-overt); }
  .active\:scale-95:active { transform: scale(0.95); }
}
```

## Best Practices

### When to Use Utilities

Use utility classes when:

1. **Building one-off UI elements** that don't warrant a dedicated component
2. **Prototyping designs** quickly without writing new CSS
3. **Adjusting components** for specific contexts
4. **Creating spacing and layout** throughout your application
5. **Fine-tuning designs** without adding custom CSS

### When to Use Components Instead

Use components instead of utilities when:

1. **The same pattern repeats** throughout your application
2. **The element has complex behavior** beyond simple styling
3. **The styling is too complex** to express cleanly with utilities
4. **You need to ensure consistency** across multiple instances
5. **The pattern includes accessibility logic** like keyboard handling

### Utility-First Approach

1. **Start with utilities**: Begin building with utility classes
2. **Extract components**: When patterns repeat, extract them into components
3. **Customize with utilities**: Use utilities to adapt components to specific contexts

### Naming and Organization

1. **Follow consistent naming**: Use the established naming pattern
2. **Group related utilities**: Keep related utilities together in your code
3. **Document utility purpose**: Add comments to explain complex utilities
4. **Consider responsive variants**: Create responsive variants for key utilities

### Performance Considerations

1. **Selective inclusion**: Consider only including the utilities you use
2. **Compression**: Use gzip/brotli compression to minimize transfer size
3. **Cache effectively**: Leverage browser caching for utility CSS
4. **Consider CSS-in-JS**: For dynamic utilities, consider CSS-in-JS approaches

## Complete Reference

The Utilities layer includes the following categories:

1. **Colors**
   - Background colors
   - Text colors
   - Border colors
   
2. **Typography**
   - Font family
   - Font size
   - Font weight
   - Line height
   - Letter spacing
   - Text alignment
   
3. **Spacing**
   - Margin
   - Padding
   - Gap
   
4. **Borders**
   - Border width
   - Border style
   - Border radius
   
5. **Effects**
   - Shadows
   - Opacity
   
6. **Layout**
   - Display
   - Position
   - Z-index
   - Width and height
   - Overflow
   
7. **Flexbox**
   - Flex direction
   - Flex wrapping
   - Flex grow/shrink
   - Alignment
   
8. **Grid**
   - Grid columns
   - Grid rows
   - Grid placement
   
9. **Interactivity**
   - Cursor
   - Pointer events
   - User select
   
10. **Accessibility**
    - Screen reader utilities
    - Focus management

For a comprehensive list of all available utility classes, refer to the utilities.css file.


================================================
FILE: src/components.css
================================================
/* ================================================ */
/* ==            @layer components               == */
/* ================================================ */
@layer components {
  /* Apply base styles to common elements using NEW theme variables */
  body {
    background-color: var(--base);
    color: var(--text-default);
  }

  a {
    color: var(--text-link);
    text-decoration: var(--link-decoration);
    text-decoration-thickness: var(--link-underline-thickness);
    text-underline-offset: var(--link-underline-offset);
    transition: color var(--link-transition-duration) var(--link-transition-timing),
                text-decoration-color var(--link-transition-duration) var(--link-transition-timing);
  }
  a:hover, a:focus-visible {
    color: var(--text-link-hover);
    text-decoration: var(--link-decoration-hover);
    text-decoration-thickness: var(--link-underline-thickness);
    text-underline-offset: var(--link-underline-offset);
  }

  /* Basic Button Styling (Structure in defaults, base style here) */
  .button {
    display: inline-flex; align-items: center; justify-content: center;
    padding: 0.6em 1.2em; border-radius: var(--radius-md);
    border: var(--border-width) solid var(--outline-default); /* Default outline */
    background-color: var(--surface-default); /* Default surface */
    color: var(--text-default); /* Use default text */
    font-weight: 500; text-align: center; cursor: pointer;
    transition: background-color 150ms ease-out, border-color 150ms ease-out, color 150ms ease-out, box-shadow 150ms ease-out;
    user-select: none; line-height: 1.2;
  }
   .button:hover:not([disabled]) {
     border-color: var(--outline-overt);
     background-color: var(--highlight-bg-subtle); /* Subtle highlight on hover */
   }
  .button:focus-visible {
     outline: var(--border-width-thick) solid var(--outline-focus);
     outline-offset: 2px;
     border-color: transparent; /* Hide border when outline is visible */
  }
  .button[disabled] {
    opacity: 0.5; cursor: not-allowed;
    background-color: var(--highlight-bg-muted);
    border-color: var(--outline-muted);
  }

  /* Input field styling */
  .input-field {
    display: block; width: 100%; padding: 0.6em 0.8em;
    border-radius: var(--radius-md);
    border: var(--border-width) solid var(--outline-default);
    background-color: var(--surface-subtle);
    color: var(--text-default);
    transition: border-color 150ms ease-out, box-shadow 150ms ease-out;
  }
  .input-field::placeholder { color: var(--text-muted); opacity: 1; }
  .input-field:hover:not([disabled]) { border-color: var(--outline-overt); }
  .input-field:focus, .input-field:focus-visible {
    outline: none; border-color: var(--outline-focus);
    box-shadow: 0 0 0 var(--border-width-thick) oklch(from var(--outline-focus) l c h / 0.3);
  }
  .input-field[disabled] { opacity: 0.6; background-color: var(--surface-muted); border-color: var(--outline-subtle); cursor: not-allowed; }
  .input-field:invalid { border-color: var(--error); box-shadow: 0 0 0 var(--border-width-thick) oklch(from var(--error) l c h / 0.3); }

  /* Custom Select Arrow */
  select.input-field {
    background-image: linear-gradient(45deg, transparent 50%, var(--text-subtle) 50%), linear-gradient(135deg, var(--text-subtle) 50%, transparent 50%);
    background-position: right 0.8em top 55%, right calc(0.8em + 5px) top 55%;
    background-size: 5px 5px, 5px 5px;
    background-repeat: no-repeat;
  }
  select.input-field:-moz-focusring { color: transparent; text-shadow: 0 0 0 var(--text-default); }

  /* Checkbox/Radio Theming */
  input[type="checkbox"], input[type="radio"] {
    border-color: var(--outline-default);
    background-color: var(--surface-subtle);
  }
  input[type="checkbox"]:hover:not(:checked):not([disabled]),
  input[type="radio"]:hover:not(:checked):not([disabled]) {
    border-color: var(--outline-overt);
    background-color: var(--highlight-bg-subtle);
  }
  input[type="checkbox"]:checked, input[type="radio"]:checked {
    background-color: var(--accent);
    border-color: var(--accent);
  }
  input[type="checkbox"]:checked:hover:not([disabled]),
  input[type="radio"]:checked:hover:not([disabled]) {
    background-color: var(--accent-overt);
    border-color: var(--accent-overt);
  }
  input[type="checkbox"]::before, input[type="radio"]::before {
    box-shadow: inset 1em 1em var(--text-on-accent); /* Use contrast text */
  }
  input[type="checkbox"]:checked::before, input[type="radio"]:checked::before {
     /* Style for the checkmark/dot */
  }

  /* Basic card structure */
  .card {
     --bg: var(--surface-default); /* Set local --bg */
     background-color: var(--bg);
     color:     var(--auto-contrast-text, oklch(
  from var(--bg, currentColor)
  clamp(0.1, (var(--l-threshold, 0.65) / l - 1) * 999, 0.98)
  min(c, var(--c-threshold, 0.08))
  h
)); /* Use auto-contrast */
     border-radius: var(--radius-lg);
     padding: 1.5rem;
     border: var(--border-width) solid var(--outline-subtle);
     box-shadow: 0 2px 5px oklch(from var(--base) calc(l - 50%) 0.02 h / 0.1);
  }

  /* Code block styling */
  pre {
    background-color: var(--code-block-bg);
    border-color: var(--code-block-border);
    color: var(--text-default); /* Or define --text-code */
  }
  :not(pre) > code, kbd, samp {
    background-color: var(--code-inline-bg);
    border-color: var(--code-inline-border);
    color: var(--text-default); /* Or define --text-code */
  }
  /* Blockquote styling */
  blockquote {
    border-inline-start-color: var(--blockquote-border);
    color: var(--text-subtle);
  }
  /* Horizontal Rule styling */
  hr { border-block-start-color: var(--hr-color); }
  /* Table styling */
  table { border-color: var(--table-border); }
  th, td { border-bottom-color: var(--table-border); }
  thead th {
    background-color: var(--table-header-bg);
    color: var(--text-overt); /* Use overt text for header */
   }
  tbody tr:hover {
    --bg: var(--table-row-hover-bg); /* Set local --bg */
    background-color: var(--bg);
    color:     var(--auto-contrast-text, oklch(
  from var(--bg, currentColor)
  clamp(0.1, (var(--l-threshold, 0.65) / l - 1) * 999, 0.98)
  min(c, var(--c-threshold, 0.08))
  h
)); /* Auto contrast on hover */
  }
  /* Enhanced Form Focus States */
  input:focus-visible, select:focus-visible, textarea:focus-visible {
    outline: var(--input-focus-ring-width) var(--focus-ring-style) var(--focus-ring-color);
    outline-offset: var(--input-focus-ring-offset);
    background-color: var(--input-focus-bg);
    border-color: var(--outline-focus);
  }

  button:focus-visible, 
  a:focus-visible,
  [tabindex]:focus-visible {
    outline: var(--focus-ring-width) var(--focus-ring-style) var(--focus-ring-color);
    outline-offset: var(--focus-ring-offset);
    box-shadow: none;
  }
  
  /* Focus Ring Color */
  :focus-visible { outline-color: var(--outline-focus); }

  /* Contrast Pair Component */
  .contrast-pair {
    --bg: var(--pair-color, var(--accent));
    background-color: var(--bg);
    color:     var(--auto-contrast-text, oklch(
  from var(--bg, currentColor)
  clamp(0.1, (var(--l-threshold, 0.65) / l - 1) * 999, 0.98)
  min(c, var(--c-threshold, 0.08))
  h
));
    padding: 1rem; border-radius: var(--radius-md);
  }
} /* End of @layer components */


================================================
FILE: src/defaults.css
================================================
/* ================================================ */
/* ==            @layer defaults                 == */
/* ================================================ */
/* Purpose: Apply structural styles and basic appearance */
/* using variables defined in the NEW @layer theme. */
@layer defaults {

  /* --- Base Body & Document Styles --- */
  body {
    font-family: var(--font-primary, sans-serif); /* Keep font variables if defined elsewhere */
    color: var(--text-default); /* UPDATED */
    background-color: var(--base); /* UPDATED */
    line-height: var(--body-line-height, 1.5);

    -webkit-font-smoothing: var(--font-smoothing-webkit, antialiased);
    -moz-osx-font-smoothing: var(--font-smoothing-moz, grayscale);
    font-synthesis: var(--font-synthesis, none);
    text-rendering: var(--text-rendering, optimizeLegibility);
    hyphens: var(--body-hyphens, auto);
    scroll-behavior: var(--scroll-behavior, smooth);
  }

  /* ::selection is handled in @theme */

  /* --- Typography Defaults --- */
  h1, h2, h3, h4, h5, h6, p, ul, ol, dl, pre, blockquote, figure, table, hr, details {
    margin-block: 0 var(--space-flow, 1em);
  }
  :is(article, section, aside, div, li, dd, dt, blockquote) > :last-child {
    margin-block-end: 0;
  }

  h1, h2, h3, h4, h5, h6 {
    font-weight: var(--font-weight-heading, 600);
    line-height: var(--line-height-heading, 1.2);
    color: var(--text-overt); /* UPDATED */
    letter-spacing: var(--letter-spacing-heading, normal);
  }
  h1 { font-size: var(--font-size-h1, 2.5rem); }
  h2 { font-size: var(--font-size-h2, 2.0rem); }
  h3 { font-size: var(--font-size-h3, 1.75rem); }
  h4 { font-size: var(--font-size-h4, 1.5rem); }
  h5 { font-size: var(--font-size-h5, 1.25rem); }
  h6 { font-size: var(--font-size-h6, 1.0rem); letter-spacing: var(--letter-spacing-h6, 0.5px); text-transform: var(--text-transform-h6, uppercase); }

  p {
    line-height: var(--body-line-height, 1.6);
    color: var(--text-default); /* UPDATED (use default body text) */
  }

  /* Lists */
  ul, ol { padding-inline-start: var(--space-list-indent, 1.5em); }
  ul { list-style: var(--list-style-unordered, disc); }
  ol { list-style: var(--list-style-ordered, decimal); }
  li { margin-block-end: var(--space-list-item, 0.5em); }
  li > ul, li > ol { margin-block-start: var(--space-list-item, 0.5em); margin-block-end: 0; }
  dt { font-weight: var(--font-weight-medium, 500); color: var(--text-overt); } /* UPDATED */
  dd { padding-inline-start: var(--space-list-indent, 1.5em); color: var(--text-subtle); } /* UPDATED */
  dd + dt { margin-block-start: var(--space-md, 1rem); }

  /* Links - Styling primarily handled in @components */
  a {
    /* Base color set in @components */
    text-decoration: var(--link-decoration, none); /* Keep structural */
  }

  /* Code blocks and inline code - Structure only, colors in @components */
  pre, code, kbd, samp {
    font-family: var(--font-mono, monospace);
    font-size: var(--font-size-code, 0.9em);
    line-height: var(--line-height-code, 1.4);
    /* color: handled in @components */
  }
  pre {
    padding: var(--space-code-block-y, 0.8em) var(--space-code-block-x, 1em);
    border-radius: var(--radius-md, 6px);
    overflow-x: auto;
    border-width: var(--border-width, 1px);
    border-style: solid;
    /* background/border color: handled in @components */
  }
  :not(pre) > code, kbd, samp {
    padding: var(--space-code-inline-y, 0.2em) var(--space-code-inline-x, 0.4em);
    border-radius: var(--radius-sm, 3px);
    border-width: var(--border-width, 1px);
    border-style: solid;
    /* background/border color: handled in @components */
  }
  kbd { letter-spacing: 0.5px; }

  /* Blockquotes - Structure only, colors in @components */
  blockquote {
    margin-inline: var(--space-blockquote-margin-inline, 1em);
    padding-inline-start: var(--space-blockquote-pad, 1em);
    border-inline-start-width: var(--border-width-blockquote, 3px);
    border-inline-start-style: solid;
    /* color/border color: handled in @components */
  }

  /* Horizontal Rule - Structure only, colors in @components */
  hr {
    border: none;
    border-block-start-width: var(--border-width, 1px);
    border-block-start-style: solid;
    /* color: handled in @components */
  }

  /* --- Form Element Defaults --- */
  input, select, textarea, fieldset {
    padding: var(--space-input-y, 0.6em) var(--space-input-x, 0.8em);
    border-width: var(--border-width, 1px);
    border-style: solid;
    border-radius: var(--radius-md, 6px);
    font-size: var(--font-size-input, 1rem);
    transition: border-color var(--transition-duration, 150ms) var(--transition-timing, ease-out),
                box-shadow var(--transition-duration, 150ms) var(--transition-timing, ease-out),
                background-color var(--transition-duration, 150ms) var(--transition-timing, ease-out);
    width: 100%;
    /* color/border/background: handled in @components */
  }
  }
  fieldset {
    padding: var(--space-fieldset-y, 1.5em) var(--space-fieldset-x, 1.2em);
    border-color: var(--outline-default); /* UPDATED */
  }
  legend {
    padding-inline: var(--space-xs, 0.5rem);
    font-weight: var(--font-weight-medium, 500);
    color: var(--text-overt); /* UPDATED */
  }
  input[type="checkbox"], input[type="radio"], input[type="submit"], input[type="button"], input[type="reset"], button {
    width: auto;
  }

  /* Button Structure - Colors applied via utilities in @utilities */
  button, input[type="button"], input[type="submit"], input[type="reset"] {
    padding: var(--space-button-y, 0.7em) var(--space-button-x, 1.3em);
    border-radius: var(--radius-md, 6px);
    font-weight: var(--font-weight-button, 500);
    border-width: var(--border-width-button, 1px);
    border-style: solid;
    transition: background-color var(--transition-duration, 150ms) var(--transition-timing, ease-out),
                border-color var(--transition-duration, 150ms) var(--transition-timing, ease-out),
                color var(--transition-duration, 150ms) var(--transition-timing, ease-out),
                box-shadow var(--transition-duration, 150ms) var(--transition-timing, ease-out),
                transform calc(var(--transition-duration, 150ms) / 2) var(--transition-timing, ease-out);
    line-height: 1;
    box-shadow: var(--shadow-button, none); /* Keep shadows if defined elsewhere */
    /* Colors/borders applied via utility classes */
  }
  /* Hover/Active structure - styles may be overridden by utilities */
  button:hover:not([disabled]),
  input[type="button"]:hover:not([disabled]),
  input[type="submit"]:hover:not([disabled]),
  input[type="reset"]:hover:not([disabled]) {
    transform: var(--transform-button-hover, translateY(-1px));
    box-shadow: var(--shadow-button-hover, 0 2px 4px oklch(from var(--base) calc(l - 50%) 0.02 h / 0.1)); /* Example subtle shadow */
  }
  button:active:not([disabled]),
  input[type="button"]:active:not([disabled]),
  input[type="submit"]:active:not([disabled]),
  input[type="reset"]:active:not([disabled]) {
    transform: var(--transform-button-active, translateY(0px));
    box-shadow: var(--shadow-button-active, none);
  }

  /* Select element structure - Arrow appearance handled in @components */
  select {
    padding-right: var(--space-select-arrow-gap, calc(var(--space-input-x, 0.8em) * 3));
  }

  /* Checkbox/Radio structure - Colors handled in @components */
  input[type="checkbox"], input[type="radio"] {
    appearance: var(--appearance-checkbox-radio, none);
    -webkit-appearance: none; -moz-appearance: none;
    border-width: var(--border-width, 1px); border-style: solid;
    width: var(--size-checkbox-radio, 1.1em); height: var(--size-checkbox-radio, 1.1em);
    margin-inline-end: var(--space-checkbox-radio-label-gap, 0.5em);
    vertical-align: middle; position: relative; display: inline-grid; place-content: center;
    /* border-color: handled in @components */
  }
  input[type="checkbox"] { border-radius: var(--radius-sm, 3px); }
  input[type="radio"] { border-radius: 50%; }
  /* Indicator structure */
  input[type="checkbox"]::before, input[type="radio"]::before {
    content: ''; width: 60%; height: 60%; transform: scale(0);
    transition: transform 100ms ease-in-out;
    /* background/box-shadow color: handled in @components */
  }
  input[type="radio"]::before { border-radius: 50%; }
  input[type="checkbox"]:checked::before, input[type="radio"]:checked::before { transform: scale(1); }

  /* Disabled State Opacity */
  button[disabled], input[disabled], select[disabled], textarea[disabled], fieldset[disabled] {
    opacity: var(--opacity-disabled, 0.5);
  }
  fieldset[disabled] * { cursor: not-allowed; }

  /* --- Table Defaults - Structure only, colors in @components --- */
  table {
    width: 100%;
    border-width: var(--border-width, 1px);
    border-style: solid;
    border-radius: var(--radius-lg, 8px);
    overflow: hidden;
    /* border-color: handled in @components */
  }
  th, td {
    padding: var(--space-table-cell-y, 0.8em) var(--space-table-cell-x, 1em);
    text-align: left; vertical-align: top;
    border-bottom-width: var(--border-width, 1px); border-bottom-style: solid;
    /* border-bottom-color: handled in @components */
  }
  thead th {
    font-weight: var(--font-weight-heading, 600);
    border-bottom-width: calc(var(--border-width, 1px) * 2);
    vertical-align: bottom;
    /* background/color: handled in @components */
  }
  tbody tr:last-child th, tbody tr:last-child td { border-bottom: none; }

  /* --- Basic Utilities Setup --- */
  .container {
    width: min(100% - (var(--space-container-padding, 1rem) * 2), var(--width-container-max, 1100px));
    margin-inline: auto;
  }
  .display-none { display: none !important; }
  .box { padding: var(--b-p, 0); margin: var(--b-m, 0); border-width: var(--b-bw, 0); border-style: solid; border-color: var(--b-bc, transparent); border-radius: var(--b-r, 0); background-color: var(--b-bg, transparent); color: var(--b-fg, inherit); }
  .box[style*="--b-px"] { padding-inline: var(--b-px); }
  .box[style*="--b-py"] { padding-block: var(--b-py); }
  .box[style*="--b-mx"] { margin-inline: var(--b-mx); }
  .box[style*="--b-my"] { margin-block: var(--b-my); }
  .cq-container, .cq { container-type: var(--cq-type, inline-size); container-name: var(--cq-name, default); }

  /* --- Accessibility Enhancements --- */
  :focus-visible { /* Structure only, color handled in @components */
    outline-style: solid;
    outline-width: var(--focus-ring-width, 2px);
    outline-offset: var(--focus-ring-offset, 2px);
    box-shadow: none;
  }
  :target { scroll-margin-block-start: var(--space-target-margin, 5ex); }

  /* --- Reduced Motion Preferences --- */
  @media (prefers-reduced-motion: reduce) {
    html { scroll-behavior: auto !important; }
    *, *::before, *::after { animation-duration: 0.01ms !important; animation-iteration-count: 1 !important; transition-duration: 0.01ms !important; transition-delay: 0ms !important; }
  }

  /* --- View Transition Structure --- */
  ::view-transition-old(root), ::view-transition-new(root) { animation-duration: var(--transition-duration-page, 300ms); animation-timing-function: var(--transition-timing-page, ease-in-out); }
  ::view-transition-old(root) { animation-name: var(--view-transition-old, fade-out); }
  ::view-transition-new(root) { animation-name: var(--view-transition-new, fade-in); z-index: 1; }
  @keyframes fade-in { from { opacity: 0; } }
  @keyframes fade-out { to { opacity: 0; } }

} /* End of @layer defaults */


================================================
FILE: src/engine.css
================================================
/* ================================================ */
/* ==              @layer engine                 == */
/* ================================================ */
@layer engine {
 :root {
    /* Lightness delta percentages */
    --l-delta-0: calc(0 / 100); --l-delta-1: calc(2 / 100); --l-delta-2: calc(4 / 100); --l-delta-3: calc(7 / 100);
    --l-delta-4: calc(10 / 100); --l-delta-5: calc(14 / 100); --l-delta-6: calc(19 / 100); --l-delta-7: calc(25 / 100);
    --l-delta-8: calc(32 / 100); --l-delta-9: calc(40 / 100); --l-delta-10: calc(50 / 100); --l-delta-11: calc(60 / 100);
    --l-delta-12: calc(70 / 100); --l-delta-13: calc(80 / 100); --l-delta-14: calc(90 / 100);
    --l-delta-0-down: calc(-1 * var(--l-delta-0)); --l-delta-1-down: calc(-1 * var(--l-delta-1));
    --l-delta-2-down: calc(-1 * var(--l-delta-2)); --l-delta-3-down: calc(-1 * var(--l-delta-3));
    --l-delta-4-down: calc(-1 * var(--l-delta-4)); --l-delta-5-down: calc(-1 * var(--l-delta-5));
    --l-delta-6-down: calc(-1 * var(--l-delta-6)); --l-delta-7-down: calc(-1 * var(--l-delta-7));
    --l-delta-8-down: calc(-1 * var(--l-delta-8)); --l-delta-9-down: calc(-1 * var(--l-delta-9));
    --l-delta-10-down: calc(-1 * var(--l-delta-10)); --l-delta-11-down: calc(-1 * var(--l-delta-11));
    --l-delta-12-down: calc(-1 * var(--l-delta-12)); --l-delta-13-down: calc(-1 * var(--l-delta-13));
    --l-delta-14-down: calc(-1 * var(--l-delta-14));

    /* Chroma delta percentages */
    --c-delta-0: calc(0 / 100); --c-delta-1: calc(10 / 100); --c-delta-2: calc(20 / 100); --c-delta-3: calc(30 / 100);
    --c-delta-4: calc(40 / 100); --c-delta-5: calc(50 / 100); --c-delta-6: calc(60 / 100); --c-delta-7: calc(70 / 100);
    --c-delta-8: calc(80 / 100); --c-delta-9: calc(90 / 100); --c-delta-10: calc(100 / 100);
    --c-delta-0-down: calc(-1 * var(--c-delta-0)); --c-delta-1-down: calc(-1 * var(--c-delta-1));
    --c-delta-2-down: calc(-1 * var(--c-delta-2)); --c-delta-3-down: calc(-1 * var(--c-delta-3));
    --c-delta-4-down: calc(-1 * var(--c-delta-4)); --c-delta-5-down: calc(-1 * var(--c-delta-5));
    --c-delta-6-down: calc(-1 * var(--c-delta-6)); --c-delta-7-down: calc(-1 * var(--c-delta-7));
    --c-delta-8-down: calc(-1 * var(--c-delta-8)); --c-delta-9-down: calc(-1 * var(--c-delta-9));
    --c-delta-10-down: calc(-1 * var(--c-delta-10));

  }


}


================================================
FILE: src/index.css
================================================
/**
 * Modern CSS Reset & Component Library
 * A comprehensive CSS reset and component library with design tokens, theme engine, 
 * enhanced accessibility features, and utility-first approach.
 * 
 * Features:
 * - Zero-specificity CSS reset using :where()
 * - Modern color handling with OKLCH
 * - Comprehensive design token system
 * - Auto-calculated contrast for text
 * - Enhanced high contrast mode handling
 * - Comprehensive shadow system
 * - Enhanced focus state handling
 * - Explicit link styling
 * - Named container query breakpoints
 * - Built-in dark mode support
 * - Extensive utility class system
 * - Layout primitives
 */

/* Define the CSS cascade layers in specific order of precedence */
@layer reset, tokens, engine, theme, palette, defaults, components, utilities, layouts;

/* Import all the layers in the defined cascade order */
@import url("reset.css");
@import url("tokens.css");
@import url("engine.css");
@import url("theme.css");
@import url("palette.css");
@import url("defaults.css");
@import url("components.css");
@import url("utilities.css");
@import url("layouts.css");


================================================
FILE: src/layouts.css
================================================
@layer layouts {
  /* --- General Layout Container --- */
  .l-container { container-type: var(--l-container-type, inline-size); container-name: var(--l-container-name, layout); }
  
  /* ================== Grid Layouts ================== */
  .l-grid { display: grid; gap: var(--l-grid-gap, var(--space-md)); grid-template-columns: repeat(auto-fit, minmax(min(100%, var(--l-grid-min-item-size, 15rem)), 1fr)); container-type: inline-size; container-name: layout-grid; }
  .l-grid > * { min-width: 0; }
  @container layout-grid (min-width: var(--cq-bp-sm, 30em)) { /* ... responsive columns ... */ }
  @container layout-grid (min-width: var(--cq-bp-md, 45em)) { /* ... responsive columns ... */ }
  
  .l-two-col { display: grid; gap: var(--l-two-col-gap, var(--space-lg)); container-type: inline-size; container-name: layout-two-col; grid-template-columns: 1fr; }
  .l-two-col > * { min-width: 0; }
  @container layout-two-col (min-width: var(--l-two-col-breakpoint, var(--cq-bp-sm, 30em))) { /* ... responsive columns ... */ }
  
  .l-split { display: grid; grid-template-columns: 1fr; gap: var(--l-split-gap, var(--space-lg)); container-type: inline-size; container-name: layout-split; }
  .l-split > * { min-width: 0; }
  @container layout-split (min-width: var(--l-split-breakpoint, var(--cq-bp-sm, 30em))) { .l-split { grid-template-columns: var(--l-split-fraction, 1fr) 1fr; } }
  .l-split--no-stack { grid-template-columns: var(--l-split-fraction, 1fr) 1fr; }
  
  /* ================= Flexbox Layouts ================= */
  .l-row { display: flex; flex-wrap: var(--l-row-wrap, wrap); gap: var(--l-row-gap, var(--space-md)); container-type: inline-size; container-name: layout-row; flex-direction: column; align-items: var(--l-row-align-stacked, stretch); }
  .l-row > * { min-width: 0; }
  @container layout-row (min-width: var(--l-row-stack-breakpoint, var(--cq-bp-xs, 20em))) { .l-row:not(.l-row--force-stack) { flex-direction: var(--l-row-direction, row); align-items: var(--l-row-align, center); justify-content: var(--l-row-justify, flex-start); } }
  .l-row--no-stack { flex-direction: var(--l-row-direction, row); align-items: var(--l-row-align, center); justify-content: var(--l-row-justify, flex-start); }
  
  .l-stack { display: flex; flex-direction: column; justify-content: var(--l-stack-justify, flex-start); align-items: var(--l-stack-align, stretch); gap: var(--l-stack-gap, var(--space-md)); }
  
  .l-cluster { display: flex; flex-wrap: wrap; gap: var(--l-cluster-gap, var(--space-sm)); justify-content: var(--l-cluster-justify, flex-start); align-items: var(--l-cluster-align, center); }
  
  .l-reel { 
    display: flex; 
    gap: var(--l-reel-gap, var(--space-md)); 
    overflow-x: auto; 
    overflow-y: hidden; 
    scrollbar-width: thin; 
    scrollbar-color: var(--scrollbar-thumb-color) var(--scrollbar-track-color); 
    -webkit-overflow-scrolling: touch; 
  } /* Uses theme scrollbar vars */
  .l-reel--no-scrollbar { scrollbar-width: none; } 
  .l-reel--no-scrollbar::-webkit-scrollbar { display: none; } 
  .l-reel > * { flex-shrink: 0; } 
  .l-reel > img { height: 100%; max-height: var(--l-reel-item-max-height, 100%); width: auto; flex-basis: auto; }
  
  .l-switcher { display: flex; flex-wrap: wrap; gap: var(--l-switcher-gap, var(--space-sm)); } 
  .l-switcher > * { flex-grow: 1; flex-basis: calc((var(--l-switcher-threshold, 20rem) - 100%) * 999); }
  
  .l-spread { display: flex; flex-direction: var(--l-spread-direction, row); justify-content: space-between; align-items: var(--l-spread-align, center); gap: var(--l-spread-gap, var(--space-md)); }
  
  /* ================= Wrapper Components ================= */
  .l-pad { 
    padding: var(--l-pad-padding, var(--space-md)); 
    padding-inline: var(--l-pad-padding-x, var(--l-pad-padding, var(--space-md))); 
    padding-block: var(--l-pad-padding-y, var(--l-pad-padding, var(--space-md))); 
  }
  
  .l-center-content { 
    box-sizing: content-box; 
    margin-inline: auto; 
    max-width: var(--l-center-content-max-width, var(--width-container-max, 60ch)); 
    padding-inline: var(--l-center-content-gutter, 0); 
    text-align: var(--l-center-content-text-align, initial); 
  }
  
  .l-cover { 
    display: grid; 
    place-content: var(--l-cover-place-content, center); 
    place-items: var(--l-cover-place-items, center); 
    padding: var(--l-cover-padding, var(--space-lg)); 
    min-height: var(--l-cover-min-height, 50vh); 
    overflow: hidden; 
    text-align: var(--l-cover-text-align, center); 
  }
  
  .l-frame { 
    position: relative; 
    overflow: hidden; 
    aspect-ratio: var(--l-frame-ratio, 16 / 9); 
  } 
  .l-frame > :first-child { 
    position: absolute; 
    top: 0; 
    left: 0; 
    width: 100%; 
    height: 100%; 
    object-fit: var(--l-frame-object-fit, cover); 
    object-position: var(--l-frame-object-position, center); 
  }
  
  .l-center { 
    display: flex; 
    justify-content: var(--l-center-justify, center); 
    align-items: var(--l-center-align, center); 
    min-height: var(--l-center-min-height, auto); 
    padding: var(--l-center-padding, 0); 
  } 
  .l-center--h { align-items: initial; } 
  .l-center--v { justify-content: initial; }
  
  /* ================= Complex/Specific Layouts ================= */
  .l-sidebar { 
    display: grid; 
    gap: var(--l-sidebar-gap, var(--space-lg)); 
    container-type: inline-size; 
    container-name: layout-sidebar; 
    grid-template-areas: "content" "sidebar"; 
  }
  .l-sidebar > *:not(.l-sidebar__aside) { grid-area: content; min-width: 0; } 
  .l-sidebar > .l-sidebar__aside { grid-area: sidebar; min-width: 0; width: 100%; }
  @container layout-sidebar (min-width: var(--l-sidebar-breakpoint, var(--cq-bp-md, 45em))) { 
    .l-sidebar { 
      grid-template-columns: var(--l-sidebar-width, minmax(15rem, 25%)) 1fr; 
      grid-template-areas: "sidebar content"; 
    } 
    .l-sidebar > .l-sidebar__aside { width: auto; } 
    .l-sidebar--right { 
      grid-template-columns: 1fr var(--l-sidebar-width, minmax(15rem, 25%)); 
      grid-template-areas: "content sidebar"; 
    } 
  }
  
  .l-standard-page { 
    display: grid; 
    grid-template-rows: auto 1fr auto; 
    min-height: var(--l-standard-page-min-height, 100vh); 
    gap: var(--l-standard-page-gap, 0); 
  }
  .l-standard-page > * { min-width: 0; } 
  .l-standard-page__header { grid-row: 1; } 
  .l-standard-page__main { grid-row: 2; } 
  .l-standard-page__footer { grid-row: 3; }
  
  .l-media { 
    display: flex; 
    align-items: var(--l-media-align, flex-start); 
    gap: var(--l-media-gap, var(--space-md)); 
  }
  .l-media > :first-child { flex-shrink: 0; } 
  .l-media > :last-child { flex-grow: 1; min-width: 0; } 
  .l-media--reverse { flex-direction: row-reverse; }
  
  .l-tabs { 
    display: flex; 
    flex-direction: column; 
    gap: var(--l-tabs-gap, var(--space-md)); 
  }
  .l-tabs__list { flex-shrink: 0; } 
  .l-tabs__panel { flex-grow: 1; min-height: 0; } 
  .l-tabs--bottom { flex-direction: column-reverse; } 
  .l-tabs--left { flex-direction: row; } 
  .l-tabs--right { flex-direction: row-reverse; }
  .l-tabs--left > .l-tabs__panel, 
  .l-tabs--right > .l-tabs__panel { min-width: 0; } 
  .l-tabs--left > .l-tabs__list, 
  .l-tabs--right > .l-tabs__list { width: var(--l-tabs-side-width, max-content); flex-shrink: 0; }
}


================================================
FILE: src/palette.css
================================================
/* ================================================ */
/* ==               @layer palette               == */
/* ================================================ */
@layer palette {
  :root {
    /* Max Chroma Clamps */
    --clamp-max-c-0: var(--max-chroma-0); --clamp-max-c-1: var(--max-chroma-1);
    --clamp-max-c-2: var(--max-chroma-2); --clamp-max-c-3: var(--max-chroma-3);
    --clamp-max-c-4: var(--max-chroma-4); --clamp-max-c-5: var(--max-chroma-5);
    --clamp-max-c-6: var(--max-chroma-6);
    --clamp-error-max-c-2: calc(var(--max-chroma-2) * 1.1); --clamp-error-max-c-3: calc(var(--max-chroma-3) * 1.1); --clamp-error-max-c-4: calc(var(--max-chroma-4) * 1.1);
    --clamp-orange-max-c-2: calc(var(--max-chroma-2) * 1.1); --clamp-orange-max-c-3: calc(var(--max-chroma-3) * 1.1); --clamp-orange-max-c-4: calc(var(--max-chroma-4) * 1.1);
    --clamp-neutral-max-c-0: calc(var(--max-chroma-0) * 0.5); --clamp-neutral-max-c-1: calc(var(--max-chroma-1) * 0.5); --clamp-neutral-max-c-2: calc(var(--max-chroma-2) * 0.5);
    --clamp-neutral-max-c-3: calc(var(--max-chroma-3) * 0.5); --clamp-neutral-max-c-4: calc(var(--max-chroma-4) * 0.5); --clamp-neutral-max-c-5: calc(var(--max-chroma-5) * 0.5); --clamp-neutral-max-c-6: calc(var(--max-chroma-6) * 0.5);

    /* Gray Scale */
    --gray-0: oklch(var(--scale-l-0) 0 0); --gray-1: oklch(var(--scale-l-1) 0 0); --gray-2: oklch(var(--scale-l-2) 0 0); --gray-3: oklch(var(--scale-l-3) 0 0); --gray-4: oklch(var(--scale-l-4) 0 0); --gray-5: oklch(var(--scale-l-5) 0 0); --gray-6: oklch(var(--scale-l-6) 0 0); --gray-7: oklch(var(--scale-l-7) 0 0); --gray-8: oklch(var(--scale-l-8) 0 0); --gray-9: oklch(var(--scale-l-9) 0 0); --gray-10: oklch(var(--scale-l-10) 0 0); --gray-11: oklch(var(--scale-l-11) 0 0); --gray-12: oklch(var(--scale-l-12) 0 0);
    /* Neutral Scale */
    --neutral-0: oklch(var(--scale-l-0) min(var(--scale-c-0), var(--clamp-neutral-max-c-0)) var(--neutral-h)); --neutral-1: oklch(var(--scale-l-1) min(var(--scale-c-1), var(--clamp-neutral-max-c-0)) var(--neutral-h)); --neutral-2: oklch(var(--scale-l-2) min(var(--scale-c-1), var(--clamp-neutral-max-c-1)) var(--neutral-h)); --neutral-3: oklch(var(--scale-l-3) min(var(--scale-c-1), var(--clamp-neutral-max-c-1)) var(--neutral-h)); --neutral-4: oklch(var(--scale-l-4) min(var(--scale-c-1), var(--clamp-neutral-max-c-2)) var(--neutral-h)); --neutral-5: oklch(var(--scale-l-5) min(var(--scale-c-2), var(--clamp-neutral-max-c-2)) var(--neutral-h)); --neutral-6: oklch(var(--scale-l-6) min(var(--scale-c-2), var(--clamp-neutral-max-c-3)) var(--neutral-h)); --neutral-7: oklch(var(--scale-l-7) min(var(--scale-c-2), var(--clamp-neutral-max-c-3)) var(--neutral-h)); --neutral-8: oklch(var(--scale-l-8) min(var(--scale-c-2), var(--clamp-neutral-max-c-4)) var(--neutral-h)); --neutral-9: oklch(var(--scale-l-9) min(var(--scale-c-2), var(--clamp-neutral-max-c-4)) var(--neutral-h)); --neutral-10: oklch(var(--scale-l-10) min(var(--scale-c-1), var(--clamp-neutral-max-c-5)) var(--neutral-h)); --neutral-11: oklch(var(--scale-l-11) min(var(--scale-c-1), var(--clamp-neutral-max-c-5)) var(--neutral-h)); --neutral-12: oklch(var(--scale-l-12) min(var(--scale-c-1), var(--clamp-neutral-max-c-6)) var(--neutral-h));
    /* Accent Scale */
    --accent-palette-0: oklch(var(--scale-l-0) min(var(--scale-c-1), var(--clamp-max-c-0)) var(--accent-h)); --accent-palette-1: oklch(var(--scale-l-1) min(var(--scale-c-2), var(--clamp-max-c-0)) var(--accent-h)); --accent-palette-2: oklch(var(--scale-l-2) min(var(--scale-c-3), var(--clamp-max-c-1)) var(--accent-h)); --accent-palette-3: oklch(var(--scale-l-3) min(var(--scale-c-4), var(--clamp-max-c-1)) var(--accent-h)); --accent-palette-4: oklch(var(--scale-l-4) min(var(--scale-c-5), var(--clamp-max-c-2)) var(--accent-h)); --accent-palette-5: oklch(var(--scale-l-5) min(var(--scale-c-7), var(--clamp-max-c-2)) var(--accent-h)); --accent-palette-6: oklch(var(--scale-l-6) min(var(--scale-c-8), var(--clamp-max-c-3)) var(--accent-h)); --accent-palette-7: oklch(var(--scale-l-7) min(var(--scale-c-9), var(--clamp-max-c-3)) var(--accent-h)); --accent-palette-8: oklch(var(--scale-l-8) min(var(--scale-c-8), var(--clamp-max-c-4)) var(--accent-h)); --accent-palette-9: oklch(var(--scale-l-9) min(var(--scale-c-7), var(--clamp-max-c-4)) var(--accent-h)); --accent-palette-10: oklch(var(--scale-l-10) min(var(--scale-c-5), var(--clamp-max-c-5)) var(--accent-h)); --accent-palette-11: oklch(var(--scale-l-11) min(var(--scale-c-4), var(--clamp-max-c-5)) var(--accent-h)); --accent-palette-12: oklch(var(--scale-l-12) min(var(--scale-c-3), var(--clamp-max-c-6)) var(--accent-h));
    /* Secondary Scale */
    --secondary-palette-0: oklch(var(--scale-l-0) min(var(--scale-c-1), var(--clamp-max-c-0)) var(--secondary-h)); --secondary-palette-1: oklch(var(--scale-l-1) min(var(--scale-c-2), var(--clamp-max-c-0)) var(--secondary-h)); --secondary-palette-2: oklch(var(--scale-l-2) min(var(--scale-c-3), var(--clamp-max-c-1)) var(--secondary-h)); --secondary-palette-3: oklch(var(--scale-l-3) min(var(--scale-c-4), var(--clamp-max-c-1)) var(--secondary-h)); --secondary-palette-4: oklch(var(--scale-l-4) min(var(--scale-c-5), var(--clamp-max-c-2)) var(--secondary-h)); --secondary-palette-5: oklch(var(--scale-l-5) min(var(--scale-c-7), var(--clamp-max-c-2)) var(--secondary-h)); --secondary-palette-6: oklch(var(--scale-l-6) min(var(--scale-c-8), var(--clamp-max-c-3)) var(--secondary-h)); --secondary-palette-7: oklch(var(--scale-l-7) min(var(--scale-c-9), var(--clamp-max-c-3)) var(--secondary-h)); --secondary-palette-8: oklch(var(--scale-l-8) min(var(--scale-c-8), var(--clamp-max-c-4)) var(--secondary-h)); --secondary-palette-9: oklch(var(--scale-l-9) min(var(--scale-c-7), var(--clamp-max-c-4)) var(--secondary-h)); --secondary-palette-10: oklch(var(--scale-l-10) min(var(--scale-c-5), var(--clamp-max-c-5)) var(--secondary-h)); --secondary-palette-11: oklch(var(--scale-l-11) min(var(--scale-c-4), var(--clamp-max-c-5)) var(--secondary-h)); --secondary-palette-12: oklch(var(--scale-l-12) min(var(--scale-c-3), var(--clamp-max-c-6)) var(--secondary-h));
    /* Tertiary Scale */
    --tertiary-palette-0: oklch(var(--scale-l-0) min(var(--scale-c-1), var(--clamp-max-c-0)) var(--tertiary-h)); --tertiary-palette-1: oklch(var(--scale-l-1) min(var(--scale-c-2), var(--clamp-max-c-0)) var(--tertiary-h)); --tertiary-palette-2: oklch(var(--scale-l-2) min(var(--scale-c-3), var(--clamp-max-c-1)) var(--tertiary-h)); --tertiary-palette-3: oklch(var(--scale-l-3) min(var(--scale-c-4), var(--clamp-max-c-1)) var(--tertiary-h)); --tertiary-palette-4: oklch(var(--scale-l-4) min(var(--scale-c-5), var(--clamp-max-c-2)) var(--tertiary-h)); --tertiary-palette-5: oklch(var(--scale-l-5) min(var(--scale-c-7), var(--clamp-max-c-2)) var(--tertiary-h)); --tertiary-palette-6: oklch(var(--scale-l-6) min(var(--scale-c-8), var(--clamp-max-c-3)) var(--tertiary-h)); --tertiary-palette-7: oklch(var(--scale-l-7) min(var(--scale-c-9), var(--clamp-max-c-3)) var(--tertiary-h)); --tertiary-palette-8: oklch(var(--scale-l-8) min(var(--scale-c-8), var(--clamp-max-c-4)) var(--tertiary-h)); --tertiary-palette-9: oklch(var(--scale-l-9) min(var(--scale-c-7), var(--clamp-max-c-4)) var(--tertiary-h)); --tertiary-palette-10: oklch(var(--scale-l-10) min(var(--scale-c-5), var(--clamp-max-c-5)) var(--tertiary-h)); --tertiary-palette-11: oklch(var(--scale-l-11) min(var(--scale-c-4), var(--clamp-max-c-5)) var(--tertiary-h)); --tertiary-palette-12: oklch(var(--scale-l-12) min(var(--scale-c-3), var(--clamp-max-c-6)) var(--tertiary-h));
    
    /* Feedback Scales (Success, Warning, Error, Info) */
    /* Success Palette */
    --success-palette-0: oklch(var(--scale-l-0) min(var(--scale-c-1), var(--clamp-max-c-0)) var(--success-h));
    --success-palette-1: oklch(var(--scale-l-1) min(var(--scale-c-2), var(--clamp-max-c-0)) var(--success-h));
    --success-palette-2: oklch(var(--scale-l-2) min(var(--scale-c-3), var(--clamp-max-c-1)) var(--success-h));
    --success-palette-3: oklch(var(--scale-l-3) min(var(--scale-c-4), var(--clamp-max-c-1)) var(--success-h));
    --success-palette-4: oklch(var(--scale-l-4) min(var(--scale-c-5), var(--clamp-max-c-2)) var(--success-h));
    --success-palette-5: oklch(var(--scale-l-5) min(var(--scale-c-7), var(--clamp-max-c-2)) var(--success-h));
    --success-palette-6: oklch(var(--scale-l-6) min(var(--scale-c-8), var(--clamp-max-c-3)) var(--success-h));
    --success-palette-7: oklch(var(--scale-l-7) min(var(--scale-c-9), var(--clamp-max-c-3)) var(--success-h));
    --success-palette-8: oklch(var(--scale-l-8) min(var(--scale-c-8), var(--clamp-max-c-4)) var(--success-h));
    --success-palette-9: oklch(var(--scale-l-9) min(var(--scale-c-7), var(--clamp-max-c-4)) var(--success-h));
    --success-palette-10: oklch(var(--scale-l-10) min(var(--scale-c-5), var(--clamp-max-c-5)) var(--success-h));
    --success-palette-11: oklch(var(--scale-l-11) min(var(--scale-c-4), var(--clamp-max-c-5)) var(--success-h));
    --success-palette-12: oklch(var(--scale-l-12) min(var(--scale-c-3), var(--clamp-max-c-6)) var(--success-h));
    
    /* Warning Palette */
    --warning-palette-0: oklch(var(--scale-l-0) min(var(--scale-c-1), var(--clamp-max-c-0)) var(--warning-h));
    --warning-palette-1: oklch(var(--scale-l-1) min(var(--scale-c-2), var(--clamp-max-c-0)) var(--warning-h));
    --warning-palette-2: oklch(var(--scale-l-2) min(var(--scale-c-3), var(--clamp-max-c-1)) var(--warning-h));
    --warning-palette-3: oklch(var(--scale-l-3) min(var(--scale-c-4), var(--clamp-max-c-1)) var(--warning-h));
    --warning-palette-4: oklch(var(--scale-l-4) min(var(--scale-c-5), var(--clamp-max-c-2)) var(--warning-h));
    --warning-palette-5: oklch(var(--scale-l-5) min(var(--scale-c-7), var(--clamp-max-c-2)) var(--warning-h));
    --warning-palette-6: oklch(var(--scale-l-6) min(var(--scale-c-8), var(--clamp-max-c-3)) var(--warning-h));
    --warning-palette-7: oklch(var(--scale-l-7) min(var(--scale-c-9), var(--clamp-max-c-3)) var(--warning-h));
    --warning-palette-8: oklch(var(--scale-l-8) min(var(--scale-c-8), var(--clamp-max-c-4)) var(--warning-h));
    --warning-palette-9: oklch(var(--scale-l-9) min(var(--scale-c-7), var(--clamp-max-c-4)) var(--warning-h));
    --warning-palette-10: oklch(var(--scale-l-10) min(var(--scale-c-5), var(--clamp-max-c-5)) var(--warning-h));
    --warning-palette-11: oklch(var(--scale-l-11) min(var(--scale-c-4), var(--clamp-max-c-5)) var(--warning-h));
    --warning-palette-12: oklch(var(--scale-l-12) min(var(--scale-c-3), var(--clamp-max-c-6)) var(--warning-h));
    
    /* Error Palette */
    --error-palette-0: oklch(var(--scale-l-0) min(var(--scale-c-1), var(--clamp-max-c-0)) var(--error-h));
    --error-palette-1: oklch(var(--scale-l-1) min(var(--scale-c-2), var(--clamp-max-c-0)) var(--error-h));
    --error-palette-2: oklch(var(--scale-l-2) min(var(--scale-c-3), var(--clamp-max-c-1)) var(--error-h));
    --error-palette-3: oklch(var(--scale-l-3) min(var(--scale-c-4), var(--clamp-max-c-1)) var(--error-h));
    --error-palette-4: oklch(var(--scale-l-4) min(var(--scale-c-5), var(--clamp-error-max-c-2, var(--clamp-max-c-2))) var(--error-h));
    --error-palette-5: oklch(var(--scale-l-5) min(var(--scale-c-7), var(--clamp-error-max-c-2, var(--clamp-max-c-2))) var(--error-h));
    --error-palette-6: oklch(var(--scale-l-6) min(var(--scale-c-8), var(--clamp-error-max-c-3, var(--clamp-max-c-3))) var(--error-h));
    --error-palette-7: oklch(var(--scale-l-7) min(var(--scale-c-9), var(--clamp-error-max-c-3, var(--clamp-max-c-3))) var(--error-h));
    --error-palette-8: oklch(var(--scale-l-8) min(var(--scale-c-8), var(--clamp-error-max-c-4, var(--clamp-max-c-4))) var(--error-h));
    --error-palette-9: oklch(var(--scale-l-9) min(var(--scale-c-7), var(--clamp-error-max-c-4, var(--clamp-max-c-4))) var(--error-h));
    --error-palette-10: oklch(var(--scale-l-10) min(var(--scale-c-5), var(--clamp-max-c-5)) var(--error-h));
    --error-palette-11: oklch(var(--scale-l-11) min(var(--scale-c-4), var(--clamp-max-c-5)) var(--error-h));
    --error-palette-12: oklch(var(--scale-l-12) min(var(--scale-c-3), var(--clamp-max-c-6)) var(--error-h));
    
    /* Info Palette */
    --info-palette-0: oklch(var(--scale-l-0) min(var(--scale-c-1), var(--clamp-max-c-0)) var(--info-h));
    --info-palette-1: oklch(var(--scale-l-1) min(var(--scale-c-2), var(--clamp-max-c-0)) var(--info-h));
    --info-palette-2: oklch(var(--scale-l-2) min(var(--scale-c-3), var(--clamp-max-c-1)) var(--info-h));
    --info-palette-3: oklch(var(--scale-l-3) min(var(--scale-c-4), var(--clamp-max-c-1)) var(--info-h));
    --info-palette-4: oklch(var(--scale-l-4) min(var(--scale-c-5), var(--clamp-max-c-2)) var(--info-h));
    --info-palette-5: oklch(var(--scale-l-5) min(var(--scale-c-7), var(--clamp-max-c-2)) var(--info-h));
    --info-palette-6: oklch(var(--scale-l-6) min(var(--scale-c-8), var(--clamp-max-c-3)) var(--info-h));
    --info-palette-7: oklch(var(--scale-l-7) min(var(--scale-c-9), var(--clamp-max-c-3)) var(--info-h));
    --info-palette-8: oklch(var(--scale-l-8) min(var(--scale-c-8), var(--clamp-max-c-4)) var(--info-h));
    --info-palette-9: oklch(var(--scale-l-9) min(var(--scale-c-7), var(--clamp-max-c-4)) var(--info-h));
    --info-palette-10: oklch(var(--scale-l-10) min(var(--scale-c-5), var(--clamp-max-c-5)) var(--info-h));
    --info-palette-11: oklch(var(--scale-l-11) min(var(--scale-c-4), var(--clamp-max-c-5)) var(--info-h));
    --info-palette-12: oklch(var(--scale-l-12) min(var(--scale-c-3), var(--clamp-max-c-6)) var(--info-h));

    /* == Extended Palette (Common Colors) == */
    /* Blue Scale */
    --blue-0: oklch(var(--scale-l-0) min(var(--scale-c-1), var(--clamp-max-c-0)) var(--hue-blue)); --blue-1: oklch(var(--scale-l-1) min(var(--scale-c-2), var(--clamp-max-c-0)) var(--hue-blue)); --blue-2: oklch(var(--scale-l-2) min(var(--scale-c-3), var(--clamp-max-c-1)) var(--hue-blue)); --blue-3: oklch(var(--scale-l-3) min(var(--scale-c-4), var(--clamp-max-c-1)) var(--hue-blue)); --blue-4: oklch(var(--scale-l-4) min(var(--scale-c-5), var(--clamp-max-c-2)) var(--hue-blue)); --blue-5: oklch(var(--scale-l-5) min(var(--scale-c-7), var(--clamp-max-c-2)) var(--hue-blue)); --blue-6: oklch(var(--scale-l-6) min(var(--scale-c-8), var(--clamp-max-c-3)) var(--hue-blue)); --blue-7: oklch(var(--scale-l-7) min(var(--scale-c-9), var(--clamp-max-c-3)) var(--hue-blue)); --blue-8: oklch(var(--scale-l-8) min(var(--scale-c-8), var(--clamp-max-c-4)) var(--hue-blue)); --blue-9: oklch(var(--scale-l-9) min(var(--scale-c-7), var(--clamp-max-c-4)) var(--hue-blue)); --blue-10: oklch(var(--scale-l-10) min(var(--scale-c-5), var(--clamp-max-c-5)) var(--hue-blue)); --blue-11: oklch(var(--scale-l-11) min(var(--scale-c-4), var(--clamp-max-c-5)) var(--hue-blue)); --blue-12: oklch(var(--scale-l-12) min(var(--scale-c-3), var(--clamp-max-c-6)) var(--hue-blue));
    
    /* Red Scale */
    --red-0: oklch(var(--scale-l-0) min(var(--scale-c-1), var(--clamp-max-c-0)) var(--hue-red)); --red-1: oklch(var(--scale-l-1) min(var(--scale-c-2), var(--clamp-max-c-0)) var(--hue-red)); --red-2: oklch(var(--scale-l-2) min(var(--scale-c-3), var(--clamp-max-c-1)) var(--hue-red)); --red-3: oklch(var(--scale-l-3) min(var(--scale-c-4), var(--clamp-max-c-1)) var(--hue-red)); --red-4: oklch(var(--scale-l-4) min(var(--scale-c-5), var(--clamp-error-max-c-2, var(--clamp-max-c-2))) var(--hue-red)); --red-5: oklch(var(--scale-l-5) min(var(--scale-c-6), var(--clamp-error-max-c-2, var(--clamp-max-c-2))) var(--hue-red)); --red-6: oklch(var(--scale-l-6) min(var(--scale-c-8), var(--clamp-error-max-c-3, var(--clamp-max-c-3))) var(--hue-red)); --red-7: oklch(var(--scale-l-7) min(var(--scale-c-9), var(--clamp-error-max-c-3, var(--clamp-max-c-3))) var(--hue-red)); --red-8: oklch(var(--scale-l-8) min(var(--scale-c-9), var(--clamp-error-max-c-4, var(--clamp-max-c-4))) var(--hue-red)); --red-9: oklch(var(--scale-l-9) min(var(--scale-c-7), var(--clamp-error-max-c-4, var(--clamp-max-c-4))) var(--hue-red)); --red-10: oklch(var(--scale-l-10) min(var(--scale-c-6), var(--clamp-max-c-5)) var(--hue-red)); --red-11: oklch(var(--scale-l-11) min(var(--scale-c-4), var(--clamp-max-c-5)) var(--hue-red)); --red-12: oklch(var(--scale-l-12) min(var(--scale-c-3), var(--clamp-max-c-6)) var(--hue-red));
    
    /* Green Scale */
    --green-0: oklch(var(--scale-l-0) min(var(--scale-c-1), var(--clamp-max-c-0)) var(--hue-green)); --green-1: oklch(var(--scale-l-1) min(var(--scale-c-2), var(--clamp-max-c-0)) var(--hue-green)); --green-2: oklch(var(--scale-l-2) min(var(--scale-c-3), var(--clamp-max-c-1)) var(--hue-green)); --green-3: oklch(var(--scale-l-3) min(var(--scale-c-4), var(--clamp-max-c-1)) var(--hue-green)); --green-4: oklch(var(--scale-l-4) min(var(--scale-c-5), var(--clamp-max-c-2)) var(--hue-green)); --green-5: oklch(var(--scale-l-5) min(var(--scale-c-6), var(--clamp-max-c-2)) var(--hue-green)); --green-6: oklch(var(--scale-l-6) min(var(--scale-c-7), var(--clamp-max-c-3)) var(--hue-green)); --green-7: oklch(var(--scale-l-7) min(var(--scale-c-8), var(--clamp-max-c-3)) var(--hue-green)); --green-8: oklch(var(--scale-l-8) min(var(--scale-c-8), var(--clamp-max-c-4)) var(--hue-green)); --green-9: oklch(var(--scale-l-9) min(var(--scale-c-6), var(--clamp-max-c-4)) var(--hue-green)); --green-10: oklch(var(--scale-l-10) min(var(--scale-c-5), var(--clamp-max-c-5)) var(--hue-green)); --green-11: oklch(var(--scale-l-11) min(var(--scale-c-4), var(--clamp-max-c-5)) var(--hue-green)); --green-12: oklch(var(--scale-l-12) min(var(--scale-c-3), var(--clamp-max-c-6)) var(--hue-green));
    
    /* Slate Scale */
    --slate-0: oklch(var(--scale-l-0) min(var(--scale-c-1), var(--clamp-max-c-0)) var(--hue-slate)); --slate-1: oklch(var(--scale-l-1) min(var(--scale-c-2), var(--clamp-max-c-0)) var(--hue-slate)); --slate-2: oklch(var(--scale-l-2) min(var(--scale-c-3), var(--clamp-max-c-1)) var(--hue-slate)); --slate-3: oklch(var(--scale-l-3) min(var(--scale-c-4), var(--clamp-max-c-1)) var(--hue-slate)); --slate-4: oklch(var(--scale-l-4) min(var(--scale-c-5), var(--clamp-max-c-2)) var(--hue-slate)); --slate-5: oklch(var(--scale-l-5) min(var(--scale-c-6), var(--clamp-max-c-2)) var(--hue-slate)); --slate-6: oklch(var(--scale-l-6) min(var(--scale-c-7), var(--clamp-max-c-3)) var(--hue-slate)); --slate-7: oklch(var(--scale-l-7) min(var(--scale-c-8), var(--clamp-max-c-3)) var(--hue-slate)); --slate-8: oklch(var(--scale-l-8) min(var(--scale-c-7), var(--clamp-max-c-4)) var(--hue-slate)); --slate-9: oklch(var(--scale-l-9) min(var(--scale-c-6), var(--clamp-max-c-4)) var(--hue-slate)); --slate-10: oklch(var(--scale-l-10) min(var(--scale-c-5), var(--clamp-max-c-5)) var(--hue-slate)); --slate-11: oklch(var(--scale-l-11) min(var(--scale-c-4), var(--clamp-max-c-5)) var(--hue-slate)); --slate-12: oklch(var(--scale-l-12) min(var(--scale-c-3), var(--clamp-max-c-6)) var(--hue-slate));
    
    /* Orange Scale */
    --orange-0: oklch(var(--scale-l-0) min(var(--scale-c-1), var(--clamp-max-c-0)) var(--hue-orange)); --orange-1: oklch(var(--scale-l-1) min(var(--scale-c-2), var(--clamp-max-c-0)) var(--hue-orange)); --orange-2: oklch(var(--scale-l-2) min(var(--scale-c-3), var(--clamp-max-c-1)) var(--hue-orange)); --orange-3: oklch(var(--scale-l-3) min(var(--scale-c-4), var(--clamp-max-c-1)) var(--hue-orange)); --orange-4: oklch(var(--scale-l-4) min(var(--scale-c-5), var(--clamp-orange-max-c-2, var(--clamp-max-c-2))) var(--hue-orange)); --orange-5: oklch(var(--scale-l-5) min(var(--scale-c-6), var(--clamp-orange-max-c-2, var(--clamp-max-c-2))) var(--hue-orange)); --orange-6: oklch(var(--scale-l-6) min(var(--scale-c-8), var(--clamp-orange-max-c-3, var(--clamp-max-c-3))) var(--hue-orange)); --orange-7: oklch(var(--scale-l-7) min(var(--scale-c-9), var(--clamp-orange-max-c-3, var(--clamp-max-c-3))) var(--hue-orange)); --orange-8: oklch(var(--scale-l-8) min(var(--scale-c-8), var(--clamp-orange-max-c-4, var(--clamp-max-c-4))) var(--hue-orange)); --orange-9: oklch(var(--scale-l-9) min(var(--scale-c-7), var(--clamp-orange-max-c-4, var(--clamp-max-c-4))) var(--hue-orange)); --orange-10: oklch(var(--scale-l-10) min(var(--scale-c-5), var(--clamp-max-c-5)) var(--hue-orange)); --orange-11: oklch(var(--scale-l-11) min(var(--scale-c-4), var(--clamp-max-c-5)) var(--hue-orange)); --orange-12: oklch(var(--scale-l-12) min(var(--scale-c-3), var(--clamp-max-c-6)) var(--hue-orange));
    
    /* Amber Scale */
    --amber-0: oklch(var(--scale-l-0) min(var(--scale-c-1), var(--clamp-max-c-0)) var(--hue-amber)); --amber-1: oklch(var(--scale-l-1) min(var(--scale-c-2), var(--clamp-max-c-0)) var(--hue-amber)); --amber-2: oklch(var(--scale-l-2) min(var(--scale-c-3), var(--clamp-max-c-1)) var(--hue-amber)); --amber-3: oklch(var(--scale-l-3) min(var(--scale-c-4), var(--clamp-max-c-1)) var(--hue-amber)); --amber-4: oklch(var(--scale-l-4) min(var(--scale-c-5), var(--clamp-max-c-2)) var(--hue-amber)); --amber-5: oklch(var(--scale-l-5) min(var(--scale-c-6), var(--clamp-max-c-2)) var(--hue-amber)); --amber-6: oklch(var(--scale-l-6) min(var(--scale-c-7), var(--clamp-max-c-3)) var(--hue-amber)); --amber-7: oklch(var(--scale-l-7) min(var(--scale-c-8), var(--clamp-max-c-3)) var(--hue-amber)); --amber-8: oklch(var(--scale-l-8) min(var(--scale-c-7), var(--clamp-max-c-4)) var(--hue-amber)); --amber-9: oklch(var(--scale-l-9) min(var(--scale-c-6), var(--clamp-max-c-4)) var(--hue-amber)); --amber-10: oklch(var(--scale-l-10) min(var(--scale-c-5), var(--clamp-max-c-5)) var(--hue-amber)); --amber-11: oklch(var(--scale-l-11) min(var(--scale-c-4), var(--clamp-max-c-5)) var(--hue-amber)); --amber-12: oklch(var(--scale-l-12) min(var(--scale-c-3), var(--clamp-max-c-6)) var(--hue-amber));
    
    /* Yellow Scale */
    --yellow-0: oklch(var(--scale-l-0) min(var(--scale-c-1), var(--clamp-max-c-0)) var(--hue-yellow)); --yellow-1: oklch(var(--scale-l-1) min(var(--scale-c-2), var(--clamp-max-c-0)) var(--hue-yellow)); --yellow-2: oklch(var(--scale-l-2) min(var(--scale-c-3), var(--clamp-max-c-1)) var(--hue-yellow)); --yellow-3: oklch(var(--scale-l-3) min(var(--scale-c-4), var(--clamp-max-c-1)) var(--hue-yellow)); --yellow-4: oklch(var(--scale-l-4) min(var(--scale-c-5), var(--clamp-max-c-2)) var(--hue-yellow)); --yellow-5: oklch(var(--scale-l-5) min(var(--scale-c-6), var(--clamp-max-c-2)) var(--hue-yellow)); --yellow-6: oklch(var(--scale-l-6) min(var(--scale-c-7), var(--clamp-max-c-3)) var(--hue-yellow)); --yellow-7: oklch(var(--scale-l-7) min(var(--scale-c-8), var(--clamp-max-c-3)) var(--hue-yellow)); --yellow-8: oklch(var(--scale-l-8) min(var(--scale-c-7), var(--clamp-max-c-4)) var(--hue-yellow)); --yellow-9: oklch(var(--scale-l-9) min(var(--scale-c-6), var(--clamp-max-c-4)) var(--hue-yellow)); --yellow-10: oklch(var(--scale-l-10) min(var(--scale-c-5), var(--clamp-max-c-5)) var(--hue-yellow)); --yellow-11: oklch(var(--scale-l-11) min(var(--scale-c-4), var(--clamp-max-c-5)) var(--hue-yellow)); --yellow-12: oklch(var(--scale-l-12) min(var(--scale-c-3), var(--clamp-max-c-6)) var(--hue-yellow));
    
    /* Lime Scale */
    --lime-0: oklch(var(--scale-l-0) min(var(--scale-c-1), var(--clamp-max-c-0)) var(--hue-lime)); --lime-1: oklch(var(--scale-l-1) min(var(--scale-c-2), var(--clamp-max-c-0)) var(--hue-lime)); --lime-2: oklch(var(--scale-l-2) min(var(--scale-c-3), var(--clamp-max-c-1)) var(--hue-lime)); --lime-3: oklch(var(--scale-l-3) min(var(--scale-c-4), var(--clamp-max-c-1)) var(--hue-lime)); --lime-4: oklch(var(--scale-l-4) min(var(--scale-c-5), var(--clamp-max-c-2)) var(--hue-lime)); --lime-5: oklch(var(--scale-l-5) min(var(--scale-c-6), var(--clamp-max-c-2)) var(--hue-lime)); --lime-6: oklch(var(--scale-l-6) min(var(--scale-c-7), var(--clamp-max-c-3)) var(--hue-lime)); --lime-7: oklch(var(--scale-l-7) min(var(--scale-c-8), var(--clamp-max-c-3)) var(--hue-lime)); --lime-8: oklch(var(--scale-l-8) min(var(--scale-c-7), var(--clamp-max-c-4)) var(--hue-lime)); --lime-9: oklch(var(--scale-l-9) min(var(--scale-c-6), var(--clamp-max-c-4)) var(--hue-lime)); --lime-10: oklch(var(--scale-l-10) min(var(--scale-c-5), var(--clamp-max-c-5)) var(--hue-lime)); --lime-11: oklch(var(--scale-l-11) min(var(--scale-c-4), var(--clamp-max-c-5)) var(--hue-lime)); --lime-12: oklch(var(--scale-l-12) min(var(--scale-c-3), var(--clamp-max-c-6)) var(--hue-lime));
    
    /* Emerald Scale */
    --emerald-0: oklch(var(--scale-l-0) min(var(--scale-c-1), var(--clamp-max-c-0)) var(--hue-emerald)); --emerald-1: oklch(var(--scale-l-1) min(var(--scale-c-2), var(--clamp-max-c-0)) var(--hue-emerald)); --emerald-2: oklch(var(--scale-l-2) min(var(--scale-c-3), var(--clamp-max-c-1)) var(--hue-emerald)); --emerald-3: oklch(var(--scale-l-3) min(var(--scale-c-4), var(--clamp-max-c-1)) var(--hue-emerald)); --emerald-4: oklch(var(--scale-l-4) min(var(--scale-c-5), var(--clamp-max-c-2)) var(--hue-emerald)); --emerald-5: oklch(var(--scale-l-5) min(var(--scale-c-6), var(--clamp-max-c-2)) var(--hue-emerald)); --emerald-6: oklch(var(--scale-l-6) min(var(--scale-c-7), var(--clamp-max-c-3)) var(--hue-emerald)); --emerald-7: oklch(var(--scale-l-7) min(var(--scale-c-8), var(--clamp-max-c-3)) var(--hue-emerald)); --emerald-8: oklch(var(--scale-l-8) min(var(--scale-c-7), var(--clamp-max-c-4)) var(--hue-emerald)); --emerald-9: oklch(var(--scale-l-9) min(var(--scale-c-6), var(--clamp-max-c-4)) var(--hue-emerald)); --emerald-10: oklch(var(--scale-l-10) min(var(--scale-c-5), var(--clamp-max-c-5)) var(--hue-emerald)); --emerald-11: oklch(var(--scale-l-11) min(var(--scale-c-4), var(--clamp-max-c-5)) var(--hue-emerald)); --emerald-12: oklch(var(--scale-l-12) min(var(--scale-c-3), var(--clamp-max-c-6)) var(--hue-emerald));
    
    /* Teal Scale */
    --teal-0: oklch(var(--scale-l-0) min(var(--scale-c-1), var(--clamp-max-c-0)) var(--hue-teal)); --teal-1: oklch(var(--scale-l-1) min(var(--scale-c-2), var(--clamp-max-c-0)) var(--hue-teal)); --teal-2: oklch(var(--scale-l-2) min(var(--scale-c-3), var(--clamp-max-c-1)) var(--hue-teal)); --teal-3: oklch(var(--scale-l-3) min(var(--scale-c-4), var(--clamp-max-c-1)) var(--hue-teal)); --teal-4: oklch(var(--scale-l-4) min(var(--scale-c-5), var(--clamp-max-c-2)) var(--hue-teal)); --teal-5: oklch(var(--scale-l-5) min(var(--scale-c-6), var(--clamp-max-c-2)) var(--hue-teal)); --teal-6: oklch(var(--scale-l-6) min(var(--scale-c-7), var(--clamp-max-c-3)) var(--hue-teal)); --teal-7: oklch(var(--scale-l-7) min(var(--scale-c-8), var(--clamp-max-c-3)) var(--hue-teal)); --teal-8: oklch(var(--scale-l-8) min(var(--scale-c-7), var(--clamp-max-c-4)) var(--hue-teal)); --teal-9: oklch(var(--scale-l-9) min(var(--scale-c-6), var(--clamp-max-c-4)) var(--hue-teal)); --teal-10: oklch(var(--scale-l-10) min(var(--scale-c-5), var(--clamp-max-c-5)) var(--hue-teal)); --teal-11: oklch(var(--scale-l-11) min(var(--scale-c-4), var(--clamp-max-c-5)) var(--hue-teal)); --teal-12: oklch(var(--scale-l-12) min(var(--scale-c-3), var(--clamp-max-c-6)) var(--hue-teal));
    
    /* Cyan Scale */
    --cyan-0: oklch(var(--scale-l-0) min(var(--scale-c-1), var(--clamp-max-c-0)) var(--hue-cyan)); --cyan-1: oklch(var(--scale-l-1) min(var(--scale-c-2), var(--clamp-max-c-0)) var(--hue-cyan)); --cyan-2: oklch(var(--scale-l-2) min(var(--scale-c-3), var(--clamp-max-c-1)) var(--hue-cyan)); --cyan-3: oklch(var(--scale-l-3) min(var(--scale-c-4), var(--clamp-max-c-1)) var(--hue-cyan)); --cyan-4: oklch(var(--scale-l-4) min(var(--scale-c-5), var(--clamp-max-c-2)) var(--hue-cyan)); --cyan-5: oklch(var(--scale-l-5) min(var(--scale-c-6), var(--clamp-max-c-2)) var(--hue-cyan)); --cyan-6: oklch(var(--scale-l-6) min(var(--scale-c-7), var(--clamp-max-c-3)) var(--hue-cyan)); --cyan-7: oklch(var(--scale-l-7) min(var(--scale-c-8), var(--clamp-max-c-3)) var(--hue-cyan)); --cyan-8: oklch(var(--scale-l-8) min(var(--scale-c-7), var(--clamp-max-c-4)) var(--hue-cyan)); --cyan-9: oklch(var(--scale-l-9) min(var(--scale-c-6), var(--clamp-max-c-4)) var(--hue-cyan)); --cyan-10: oklch(var(--scale-l-10) min(var(--scale-c-5), var(--clamp-max-c-5)) var(--hue-cyan)); --cyan-11: oklch(var(--scale-l-11) min(var(--scale-c-4), var(--clamp-max-c-5)) var(--hue-cyan)); --cyan-12: oklch(var(--scale-l-12) min(var(--scale-c-3), var(--clamp-max-c-6)) var(--hue-cyan));
    
    /* Sky Scale */
    --sky-0: oklch(var(--scale-l-0) min(var(--scale-c-1), var(--clamp-max-c-0)) var(--hue-sky)); --sky-1: oklch(var(--scale-l-1) min(var(--scale-c-2), var(--clamp-max-c-0)) var(--hue-sky)); --sky-2: oklch(var(--scale-l-2) min(var(--scale-c-3), var(--clamp-max-c-1)) var(--hue-sky)); --sky-3: oklch(var(--scale-l-3) min(var(--scale-c-4), var(--clamp-max-c-1)) var(--hue-sky)); --sky-4: oklch(var(--scale-l-4) min(var(--scale-c-5), var(--clamp-max-c-2)) var(--hue-sky)); --sky-5: oklch(var(--scale-l-5) min(var(--scale-c-6), var(--clamp-max-c-2)) var(--hue-sky)); --sky-6: oklch(var(--scale-l-6) min(var(--scale-c-7), var(--clamp-max-c-3)) var(--hue-sky)); --sky-7: oklch(var(--scale-l-7) min(var(--scale-c-8), var(--clamp-max-c-3)) var(--hue-sky)); --sky-8: oklch(var(--scale-l-8) min(var(--scale-c-7), var(--clamp-max-c-4)) var(--hue-sky)); --sky-9: oklch(var(--scale-l-9) min(var(--scale-c-6), var(--clamp-max-c-4)) var(--hue-sky)); --sky-10: oklch(var(--scale-l-10) min(var(--scale-c-5), var(--clamp-max-c-5)) var(--hue-sky)); --sky-11: oklch(var(--scale-l-11) min(var(--scale-c-4), var(--clamp-max-c-5)) var(--hue-sky)); --sky-12: oklch(var(--scale-l-12) min(var(--scale-c-3), var(--clamp-max-c-6)) var(--hue-sky));
    
    /* Indigo Scale */
    --indigo-0: oklch(var(--scale-l-0) min(var(--scale-c-1), var(--clamp-max-c-0)) var(--hue-indigo)); --indigo-1: oklch(var(--scale-l-1) min(var(--scale-c-2), var(--clamp-max-c-0)) var(--hue-indigo)); --indigo-2: oklch(var(--scale-l-2) min(var(--scale-c-3), var(--clamp-max-c-1)) var(--hue-indigo)); --indigo-3: oklch(var(--scale-l-3) min(var(--scale-c-4), var(--clamp-max-c-1)) var(--hue-indigo)); --indigo-4: oklch(var(--scale-l-4) min(var(--scale-c-5), var(--clamp-max-c-2)) var(--hue-indigo)); --indigo-5: oklch(var(--scale-l-5) min(var(--scale-c-6), var(--clamp-max-c-2)) var(--hue-indigo)); --indigo-6: oklch(var(--scale-l-6) min(var(--scale-c-7), var(--clamp-max-c-3)) var(--hue-indigo)); --indigo-7: oklch(var(--scale-l-7) min(var(--scale-c-8), var(--clamp-max-c-3)) var(--hue-indigo)); --indigo-8: oklch(var(--scale-l-8) min(var(--scale-c-7), var(--clamp-max-c-4)) var(--hue-indigo)); --indigo-9: oklch(var(--scale-l-9) min(var(--scale-c-6), var(--clamp-max-c-4)) var(--hue-indigo)); --indigo-10: oklch(var(--scale-l-10) min(var(--scale-c-5), var(--clamp-max-c-5)) var(--hue-indigo)); --indigo-11: oklch(var(--scale-l-11) min(var(--scale-c-4), var(--clamp-max-c-5)) var(--hue-indigo)); --indigo-12: oklch(var(--scale-l-12) min(var(--scale-c-3), var(--clamp-max-c-6)) var(--hue-indigo));
    
    /* Violet Scale */
    --violet-0: oklch(var(--scale-l-0) min(var(--scale-c-1), var(--clamp-max-c-0)) var(--hue-violet)); --violet-1: oklch(var(--scale-l-1) min(var(--scale-c-2), var(--clamp-max-c-0)) var(--hue-violet)); --violet-2: oklch(var(--scale-l-2) min(var(--scale-c-3), var(--clamp-max-c-1)) var(--hue-violet)); --violet-3: oklch(var(--scale-l-3) min(var(--scale-c-4), var(--clamp-max-c-1)) var(--hue-violet)); --violet-4: oklch(var(--scale-l-4) min(var(--scale-c-5), var(--clamp-max-c-2)) var(--hue-violet)); --violet-5: oklch(var(--scale-l-5) min(var(--scale-c-6), var(--clamp-max-c-2)) var(--hue-violet)); --violet-6: oklch(var(--scale-l-6) min(var(--scale-c-7), var(--clamp-max-c-3)) var(--hue-violet)); --violet-7: oklch(var(--scale-l-7) min(var(--scale-c-8), var(--clamp-max-c-3)) var(--hue-violet)); --violet-8: oklch(var(--scale-l-8) min(var(--scale-c-7), var(--clamp-max-c-4)) var(--hue-violet)); --violet-9: oklch(var(--scale-l-9) min(var(--scale-c-6), var(--clamp-max-c-4)) var(--hue-violet)); --violet-10: oklch(var(--scale-l-10) min(var(--scale-c-5), var(--clamp-max-c-5)) var(--hue-violet)); --violet-11: oklch(var(--scale-l-11) min(var(--scale-c-4), var(--clamp-max-c-5)) var(--hue-violet)); --violet-12: oklch(var(--scale-l-12) min(var(--scale-c-3), var(--clamp-max-c-6)) var(--hue-violet));
    
    /* Purple Scale */
    --purple-0: oklch(var(--scale-l-0) min(var(--scale-c-1), var(--clamp-max-c-0)) var(--hue-purple)); --purple-1: oklch(var(--scale-l-1) min(var(--scale-c-2), var(--clamp-max-c-0)) var(--hue-purple)); --purple-2: oklch(var(--scale-l-2) min(var(--scale-c-3), var(--clamp-max-c-1)) var(--hue-purple)); --purple-3: oklch(var(--scale-l-3) min(var(--scale-c-4), var(--clamp-max-c-1)) var(--hue-purple)); --purple-4: oklch(var(--scale-l-4) min(var(--scale-c-5), var(--clamp-max-c-2)) var(--hue-purple)); --purple-5: oklch(var(--scale-l-5) min(var(--scale-c-6), var(--clamp-max-c-2)) var(--hue-purple)); --purple-6: oklch(var(--scale-l-6) min(var(--scale-c-7), var(--clamp-max-c-3)) var(--hue-purple)); --purple-7: oklch(var(--scale-l-7) min(var(--scale-c-8), var(--clamp-max-c-3)) var(--hue-purple)); --purple-8: oklch(var(--scale-l-8) min(var(--scale-c-7), var(--clamp-max-c-4)) var(--hue-purple)); --purple-9: oklch(var(--scale-l-9) min(var(--scale-c-6), var(--clamp-max-c-4)) var(--hue-purple)); --purple-10: oklch(var(--scale-l-10) min(var(--scale-c-5), var(--clamp-max-c-5)) var(--hue-purple)); --purple-11: oklch(var(--scale-l-11) min(var(--scale-c-4), var(--clamp-max-c-5)) var(--hue-purple)); --purple-12: oklch(var(--scale-l-12) min(var(--scale-c-3), var(--clamp-max-c-6)) var(--hue-purple));
    
    /* Fuchsia Scale */
    --fuchsia-0: oklch(var(--scale-l-0) min(var(--scale-c-1), var(--clamp-max-c-0)) var(--hue-fuchsia)); --fuchsia-1: oklch(var(--scale-l-1) min(var(--scale-c-2), var(--clamp-max-c-0)) var(--hue-fuchsia)); --fuchsia-2: oklch(var(--scale-l-2) min(var(--scale-c-3), var(--clamp-max-c-1)) var(--hue-fuchsia)); --fuchsia-3: oklch(var(--scale-l-3) min(var(--scale-c-4), var(--clamp-max-c-1)) var(--hue-fuchsia)); --fuchsia-4: oklch(var(--scale-l-4) min(var(--scale-c-5), var(--clamp-max-c-2)) var(--hue-fuchsia)); --fuchsia-5: oklch(var(--scale-l-5) min(var(--scale-c-6), var(--clamp-max-c-2)) var(--hue-fuchsia)); --fuchsia-6: oklch(var(--scale-l-6) min(var(--scale-c-7), var(--clamp-max-c-3)) var(--hue-fuchsia)); --fuchsia-7: oklch(var(--scale-l-7) min(var(--scale-c-8), var(--clamp-max-c-3)) var(--hue-fuchsia)); --fuchsia-8: oklch(var(--scale-l-8) min(var(--scale-c-7), var(--clamp-max-c-4)) var(--hue-fuchsia)); --fuchsia-9: oklch(var(--scale-l-9) min(var(--scale-c-6), var(--clamp-max-c-4)) var(--hue-fuchsia)); --fuchsia-10: oklch(var(--scale-l-10) min(var(--scale-c-5), var(--clamp-max-c-5)) var(--hue-fuchsia)); --fuchsia-11: oklch(var(--scale-l-11) min(var(--scale-c-4), var(--clamp-max-c-5)) var(--hue-fuchsia)); --fuchsia-12: oklch(var(--scale-l-12) min(var(--scale-c-3), var(--clamp-max-c-6)) var(--hue-fuchsia));
    
    /* Pink Scale */
    --pink-0: oklch(var(--scale-l-0) min(var(--scale-c-1), var(--clamp-max-c-0)) var(--hue-pink)); --pink-1: oklch(var(--scale-l-1) min(var(--scale-c-2), var(--clamp-max-c-0)) var(--hue-pink)); --pink-2: oklch(var(--scale-l-2) min(var(--scale-c-3), var(--clamp-max-c-1)) var(--hue-pink)); --pink-3: oklch(var(--scale-l-3) min(var(--scale-c-4), var(--clamp-max-c-1)) var(--hue-pink)); --pink-4: oklch(var(--scale-l-4) min(var(--scale-c-5), var(--clamp-max-c-2)) var(--hue-pink)); --pink-5: oklch(var(--scale-l-5) min(var(--scale-c-6), var(--clamp-max-c-2)) var(--hue-pink)); --pink-6: oklch(var(--scale-l-6) min(var(--scale-c-7), var(--clamp-max-c-3)) var(--hue-pink)); --pink-7: oklch(var(--scale-l-7) min(var(--scale-c-8), var(--clamp-max-c-3)) var(--hue-pink)); --pink-8: oklch(var(--scale-l-8) min(var(--scale-c-7), var(--clamp-max-c-4)) var(--hue-pink)); --pink-9: oklch(var(--scale-l-9) min(var(--scale-c-6), var(--clamp-max-c-4)) var(--hue-pink)); --pink-10: oklch(var(--scale-l-10) min(var(--scale-c-5), var(--clamp-max-c-5)) var(--hue-pink)); --pink-11: oklch(var(--scale-l-11) min(var(--scale-c-4), var(--clamp-max-c-5)) var(--hue-pink)); --pink-12: oklch(var(--scale-l-12) min(var(--scale-c-3), var(--clamp-max-c-6)) var(--hue-pink));
    
    /* Rose Scale */
    --rose-0: oklch(var(--scale-l-0) min(var(--scale-c-1), var(--clamp-max-c-0)) var(--hue-rose)); --rose-1: oklch(var(--scale-l-1) min(var(--scale-c-2), var(--clamp-max-c-0)) var(--hue-rose)); --rose-2: oklch(var(--scale-l-2) min(var(--scale-c-3), var(--clamp-max-c-1)) var(--hue-rose)); --rose-3: oklch(var(--scale-l-3) min(var(--scale-c-4), var(--clamp-max-c-1)) var(--hue-rose)); --rose-4: oklch(var(--scale-l-4) min(var(--scale-c-5), var(--clamp-max-c-2)) var(--hue-rose)); --rose-5: oklch(var(--scale-l-5) min(var(--scale-c-6), var(--clamp-max-c-2)) var(--hue-rose)); --rose-6: oklch(var(--scale-l-6) min(var(--scale-c-7), var(--clamp-max-c-3)) var(--hue-rose)); --rose-7: oklch(var(--scale-l-7) min(var(--scale-c-8), var(--clamp-max-c-3)) var(--hue-rose)); --rose-8: oklch(var(--scale-l-8) min(var(--scale-c-7), var(--clamp-max-c-4)) var(--hue-rose)); --rose-9: oklch(var(--scale-l-9) min(var(--scale-c-6), var(--clamp-max-c-4)) var(--hue-rose)); --rose-10: oklch(var(--scale-l-10) min(var(--scale-c-5), var(--clamp-max-c-5)) var(--hue-rose)); --rose-11: oklch(var(--scale-l-11) min(var(--scale-c-4), var(--clamp-max-c-5)) var(--hue-rose)); --rose-12: oklch(var(--scale-l-12) min(var(--scale-c-3), var(--clamp-max-c-6)) var(--hue-rose));
  }
}


================================================
FILE: src/reset.css
================================================
/* ================================================ */
/* ==               @layer reset                 == */
/* ================================================ */
/* Purpose: Neutralize browser styles, fix inconsistencies, */
/* establish predictable baseline behavior, and provide a clean */
/* slate with zero specificity (:where). */
@layer reset {
  /* --- Core Resets --- */
  :where(*, *::before, *::after) { margin: 0; padding: 0; box-sizing: border-box; vertical-align: baseline; min-width: 0; font: inherit; color: inherit; line-height: inherit; }
  /* --- Document Level --- */
  :where(html) { text-size-adjust: 100%; -webkit-text-size-adjust: 100%; -moz-text-size-adjust: none; tab-size: 4; height: 100%; }
  :where(body) { min-height: 100%; }
  /* --- Element Display & Behavior --- */
  :where(:is(img, picture, video, canvas, svg, :not(:defined))) { display: block; max-width: 100%; height: auto; }
  :where(svg) { fill: currentColor; stroke: currentColor; stroke-width: 0; }
  /* Form element normalization */
  :where(button, input, select, textarea) { appearance: none; -webkit-appearance: none; -moz-appearance: none; border-radius: 0; background-color: transparent; letter-spacing: inherit; border: 1px solid transparent; }
  :where(button) { border: none; background: none; text-align: inherit; }
  :where(textarea) { resize: vertical; overflow: auto; }
  /* Default cursors */
  :where(button, select:not([disabled]), input[type="button"], input[type="submit"], input[type="reset"], input[type="checkbox"], input[type="radio"], label) { cursor: pointer; }
  :where(input[type="text"], input[type="email"], input[type="search"], input[type="url"], input[type="tel"], input[type="number"], input[type="password"], textarea) { cursor: text; }
  :where([disabled]) { cursor: not-allowed; }
  /* --- Text Element Resets --- */
  :where(p, h1, h2, h3, h4, h5, h6, li, dd, dt, blockquote) { overflow-wrap: break-word; }
  :where(h1, h2, h3, h4, h5, h6) { text-wrap: balance; font-size: inherit; font-weight: inherit; }
  :where(p, blockquote, li) { text-wrap: pretty; }
  :where(a) { text-decoration: inherit; }
  :where(abbr[title]) { text-decoration: underline dotted; cursor: help; }
  /* --- Other Element Resets --- */
  :where(table) { text-indent: 0; border-color: inherit; border-collapse: collapse; border-spacing: 0; }
  :where(ul, ol) { list-style: none; }
  :where([src='']) { display: none; }
  :where(::backdrop) { all: unset; }
  :where(:not(html, body, svg, img, video, canvas, iframe, frame, object, embed, hr, :where(button, input, select, textarea), table, thead, tbody, tfoot, tr, th, td, details, summary, fieldset)) { border-style: solid; border-width: 0; }
  /* --- Accessibility & Utilities --- */
  :where([hidden]) { display: none !important; }
  :where(.visually-hidden:not(:focus):not(:active), .sr-only:not(:focus):not(:active)) { clip: rect(0 0 0 0); clip-path: inset(50%); height: 1px; overflow: hidden; position: absolute; white-space: nowrap; width: 1px; }
  /* --- Modern Feature Opt-ins --- */
  @view-transition { navigation: auto; }
} /* End of @layer reset */


================================================
FILE: src/theme.css
================================================
/* ================================================ */
/* ==               @layer theme                 == */
/* ================================================ */
@property --highlight-bg-subtle {
  syntax: '<color>'
}
@layer theme {
  /* Light Mode Theme */
  :root {
    /* Config */
    --accent-h: var(--hue-violet); --accent-c: 0.15; --accent-l: 60%;
    --secondary-hue-shift: 60; --tertiary-hue-shift: -90;
    --surface-c: 0.015; --contrast-factor: 1.0;
    --l-threshold: 0.65; --c-threshold: 0.08;
    --border-width: 1px; --border-width-thick: 2px; --border-width-thin: 0.5px;
    --radius-sm: 3px; --radius-md: 6px; --radius-lg: 8px; --radius-xl: 12px; --radius-full: 9999px;
    
    /* Enhanced Focus State Variables */
    --focus-ring-width: 2px;
    --focus-ring-offset: 2px;
    --focus-ring-color: var(--outline-focus);
    --focus-ring-style: solid;
    
    /* Form element specific focus states */
    --input-focus-ring-width: var(--focus-ring-width);
    --input-focus-ring-offset: 0px;
    --input-focus-bg: transparent;
    --input-hover-border-color: var(--outline-overt);
    
    /* Enhanced link styling variables */
    --link-decoration: none;
    --link-decoration-hover: underline;
    --link-underline-thickness: 1.5px;
    --link-underline-offset: 0.15em;
    --link-transition-duration: var(--transition-duration, 150ms);
    --link-transition-timing: var(--transition-timing, ease-out);
    
    /* Container query configuration */
    --cq-type: inline-size;
    --cq-name: default;

    /* Derived Hues */
    --secondary-h: calc(mod((var(--accent-h) + var(--secondary-hue-shift)), 360));
    --tertiary-h: calc(mod((var(--accent-h) + var(--tertiary-hue-shift)), 360));
    --neutral-h: var(--accent-h);
    /* Feedback Hues */
    --success-h: var(--hue-green); --warning-h: var(--hue-amber); --error-h: var(--hue-red); --info-h: var(--hue-blue);

    /* Semantic Color Roles (Light Mode) */
    /* Base & Bedrock */
    --base: oklch(97.5% calc(var(--surface-c) * 0.9) var(--neutral-h)); /* Use neutral hue for base */
    --bedrock: oklch(15% calc(var(--surface-c) * 1.2) var(--neutral-h)); /* Darkest color (blackish) */
    /* Surfaces - hierarchy: overt > default > base > subtle > muted */
    --surface-muted: oklch(95% calc(var(--surface-c) * 0.8) var(--neutral-h)); /* Like a disabled state, low contrast from base */
    --surface-subtle: oklch(95% calc(var(--surface-c) * 1.05) var(--neutral-h)); /* Subtle difference from base */
    --surface-default: oklch(94% calc(var(--surface-c) * 1.2) var(--neutral-h)); /* Standard surface */
    --surface-overt-dark: oklch(77.5% calc(var(--surface-c) * 2.25) var(--neutral-h)); /* Most prominent surface */
    --surface-overt-light: oklch(99.5% calc(var(--surface-c) * 0.8) var(--neutral-h)); /* Most prominent surface */
    /* Text */
    --text-muted: oklch(45% calc(var(--surface-c) * 1.5) var(--neutral-h) / 0.8);
    --text-subtle: oklch(35% calc(var(--surface-c) * 1.8) var(--neutral-h));
    --text-default: oklch(20% calc(var(--surface-c) * 2) var(--neutral-h));
    --text-overt: oklch(10% calc(var(--surface-c) * 2.2) var(--neutral-h));
    /* Links & Highlights */
    --text-link: oklch(from var(--accent) calc(l + var(--l-delta-1-down)) calc(c + var(--c-delta-1)) h);
    --text-link-hover: oklch(from var(--text-link) calc(l + var(--l-delta-2-down)) c h);
    --text-highlight-subtle: oklch(from var(--accent) calc(l + var(--l-delta-2)) calc(c + var(--c-delta-1-down)) h);
    --text-highlight-overt: oklch(from var(--accent) calc(l + var(--l-delta-1-down)) calc(c + var(--c-delta-1)) h);
    --text-highlight-bg: oklch(from var(--accent) calc(l + var(--l-delta-12)) calc(c + var(--c-delta-7-down)) h);
    /* Outlines */
    --outline-muted: oklch(from var(--base) calc(l + var(--l-delta-4-down)) calc(c + var(--c-delta-2-down)) h / 0.5);
    --outline-subtle: oklch(from var(--base) calc(l + var(--l-delta-5-down)) c h);
    --outline-default: oklch(from var(--base) calc(l + var(--l-delta-6-down)) calc(c + var(--c-delta-1)) h);
    --outline-overt: oklch(from var(--base) calc(l + var(--l-delta-7-down)) calc(c + var(--c-delta-2)) h);
    --outline-focus: oklch(var(--accent-l) var(--accent-c) var(--accent-h));
    --outline-active: oklch(from var(--accent) calc(l + var(--l-delta-2-down)) calc(c + var(--c-delta-1)) h);
    --outline-highlight-subtle: oklch(from var(--accent) calc(l + var(--l-delta-7)) calc(c + var(--c-delta-4-down)) h);
    --outline-highlight-overt: oklch(from var(--accent) calc(l + var(--l-delta-4)) calc(c + var(--c-delta-2-down)) h);
    /* Highlights (Interaction Backgrounds) */
    --highlight-bg-muted: oklch(from var(--base) calc(l + var(--l-delta-1-down)) c h);
    --highlight-bg-subtle: oklch(from var(--base) calc(l + var(--l-delta-3-down)) c h);
    --highlight-bg-overt: oklch(from var(--accent) calc(l + var(--l-delta-10)) calc(c + var(--c-delta-6-down)) h);
    /* Accent Family */
    --accent: oklch(var(--accent-l) var(--accent-c) var(--accent-h));
    --accent-muted: oklch(from var(--accent) calc(l + var(--l-delta-5)) calc(c + var(--c-delta-3-down)) h);
    --accent-subtle: oklch(from var(--accent) calc(l + var(--l-delta-2)) calc(c + var(--c-delta-1-down)) h);
    --accent-overt: oklch(from var(--accent) calc(l + var(--l-delta-3-down)) calc(c + var(--c-delta-1)) h);
    /* Secondary Family */
    --secondary-l: var(--accent-l); --secondary-c: var(--accent-c);
    --secondary: oklch(var(--secondary-l) var(--secondary-c) var(--secondary-h));
    --secondary-muted: oklch(from var(--secondary) calc(l + var(--l-delta-5)) calc(c + var(--c-delta-3-down)) h);
    --secondary-subtle: oklch(from var(--secondary) calc(l + var(--l-delta-2)) calc(c + var(--c-delta-1-down)) h);
    --secondary-overt: oklch(from var(--secondary) calc(l + var(--l-delta-3-down)) calc(c + var(--c-delta-1)) h);
    /* Tertiary Family */
    --tertiary-l: var(--accent-l); --tertiary-c: var(--accent-c);
    --tertiary: oklch(var(--tertiary-l) var(--tertiary-c) var(--tertiary-h));
    --tertiary-muted: oklch(from var(--tertiary) calc(l + var(--l-delta-5)) calc(c + var(--c-delta-3-down)) h);
    --tertiary-subtle: oklch(from var(--tertiary) calc(l + var(--l-delta-2)) calc(c + var(--c-delta-1-down)) h);
    --tertiary-overt: oklch(from var(--tertiary) calc(l + var(--l-delta-3-down)) calc(c + var(--c-delta-1)) h);
    /* Feedback Family */
    --success-c: 0.15; --success-l: 55%;
    --warning-c: 0.15; --warning-l: 70%;
    --error-c: 0.2; --error-l: 60%;
    --info-c: 0.15; --info-l: 65%;
    --success: oklch(var(--success-l) var(--success-c) var(--success-h));
    --warning: oklch(var(--warning-l) var(--warning-c) var(--warning-h));
    --error: oklch(var(--error-l) var(--error-c) var(--error-h));
    --info: oklch(var(--info-l) var(--info-c) var(--info-h));
    --text-success: var(--success); --text-warning: var(--warning); --text-error: var(--error); --text-info: var(--info);
    --surface-success: oklch(from var(--success) calc(l + var(--l-delta-11)) calc(c + var(--c-delta-6-down)) h);
    --surface-warning: oklch(from var(--warning) calc(l + var(--l-delta-10)) calc(c + var(--c-delta-6-down)) h);
    --surface-error: oklch(from var(--error) calc(l + var(--l-delta-10)) calc(c + var(--c-delta-7-down)) h);
    --surface-info: oklch(from var(--info) calc(l + var(--l-delta-10)) calc(c + var(--c-delta-6-down)) h);
    --outline-success: oklch(from var(--success) calc(l + var(--l-delta-2-down)) calc(c + var(--c-delta-1)) h);
    --outline-warning: oklch(from var(--warning) calc(l + var(--l-delta-1-down)) calc(c + var(--c-delta-1)) h);
    --outline-error: oklch(from var(--error) calc(l + var(--l-delta-1-down)) calc(c + var(--c-delta-1)) h);
    --outline-info: oklch(from var(--info) calc(l + var(--l-delta-1-down)) calc(c + var(--c-delta-1)) h);
    /* Auto-contrast text roles (will be calculated by browser using --auto-contrast-text) */
    --text-on-base: ; --text-on-bedrock: ; --text-on-surface-muted: ; --text-on-surface-subtle: ;
    --text-on-surface-default: ; --text-on-surface-overt: ;
    --text-on-accent: ; --text-on-accent-muted: ; --text-on-accent-subtle: ; --text-on-accent-overt: ;
    --text-on-secondary: ; --text-on-secondary-muted: ; --text-on-secondary-subtle: ; --text-on-secondary-overt: ;
    --text-on-tertiary: ; --text-on-tertiary-muted: ; --text-on-tertiary-subtle: ; --text-on-tertiary-overt: ;
    --text-on-highlight-muted: ; --text-on-highlight-subtle: ; --text-on-highlight-overt: ;
    --text-on-success: ; --text-on-warning: ; --text-on-error: ; --text-on-info: ;
    /* Specific Component Roles */
    --indicator-color: var(--text-on-accent); /* Checkbox/Radio checkmark */
    --scrollbar-thumb-color: var(--outline-default);
    --scrollbar-track-color: var(--surface-subtle);
    --hr-color: var(--outline-subtle);
    --table-border: var(--outline-default);
    --table-header-bg: var(--surface-subtle);
    --table-row-hover-bg: var(--highlight-bg-subtle);
    --code-block-bg: var(--surface-subtle);
    --code-block-border: var(--outline-subtle);
    --code-inline-bg: var(--surface-muted);
    --code-inline-border: var(--outline-muted);
    --blockquote-border: var(--outline-default);
  }
  /* Dark Mode Theme */
  @media (prefers-color-scheme: dark) {
    :root {
      /* Dark Mode Config Overrides */
      --accent-l: 70%; --accent-c: 0.18;
      --surface-c: 0.02; --l-threshold: 0.6;
      /* Dark Mode Role Overrides - hierarchy: overt > default > base > subtle > muted */
      --base: oklch(22% calc(var(--surface-c) * 0.9) var(--neutral-h));
      --bedrock: oklch(95% calc(var(--surface-c) * 0.7) var(--neutral-h)); /* Inverted in dark mode - lightest color */
      --surface-muted: oklch(20% calc(var(--surface-c) * 0.5) var(--neutral-h)); /* Like a disabled state, low contrast from base */
      --surface-subtle: oklch(21% calc(var(--surface-c) * 0.7) var(--neutral-h)); /* Subtle difference from base */
      --surface-default: oklch(25% var(--surface-c) var(--neutral-h)); /* Standard surface */
      --surface-overt: oklch(30% calc(var(--surface-c) * 1.2) var(--neutral-h)); /* Most prominent surface */
      --text-muted: oklch(65% calc(var(--surface-c) * 1.2) var(--neutral-h) / 0.8);
      --text-subtle: oklch(75% calc(var(--surface-c) * 1.0) var(--neutral-h));
      --text-default: oklch(88% calc(var(--surface-c) * 0.8) var(--neutral-h));
      --text-overt: oklch(95% calc(var(--surface-c) * 0.6) var(--neutral-h));
      --text-link: oklch(from var(--accent) calc(l + var(--l-delta-1)) calc(c + var(--c-delta-1-down)) h);
      --text-link-hover: oklch(from var(--text-link) calc(l + var(--l-delta-2)) c h);
      --text-highlight-bg: oklch(from var(--accent) calc(l + var(--l-delta-10-down)) calc(c + var(--c-delta-4-down)) h);
      --outline-subtle: oklch(from var(--base) calc(l + var(--l-delta-5)) c h);
      --outline-default: oklch(from var(--base) calc(l + var(--l-delta-6)) calc(c + var(--c-delta-1)) h);
      --outline-overt: oklch(from var(--base) calc(l + var(--l-delta-7)) calc(c + var(--c-delta-2)) h);
      --outline-active: oklch(from var(--accent) calc(l + var(--l-delta-2)) calc(c + var(--c-delta-1)) h);
      --outline-highlight-subtle: oklch(from var(--accent) calc(l + var(--l-delta-5-down)) calc(c + var(--c-delta-3-down)) h);
      --outline-highlight-overt: oklch(from var(--accent) calc(l + var(--l-delta-2-down)) calc(c + var(--c-delta-1-down)) h);
      --highlight-bg-muted: oklch(from var(--base) calc(l + var(--l-delta-1)) c h);
      --highlight-bg-subtle: oklch(from var(--base) calc(l + var(--l-delta-3)) c h);
      --highlight-bg-overt: oklch(from var(--accent) calc(l + var(--l-delta-7-down)) calc(c + var(--c-delta-4-down)) h);
      /* Dark Mode Feedback Roles */
      --success-l: 65%; --warning-l: 75%; --error-l: 70%; --info-l: 75%;
      /* Recalculate main, text, outline */
      --success: oklch(var(--success-l) var(--success-c) var(--success-h));
      --warning: oklch(var(--warning-l) var(--warning-c) var(--warning-h));
      --error: oklch(var(--error-l) var(--error-c) var(--error-h));
      --info: oklch(var(--info-l) var(--info-c) var(--info-h));
      --text-success: var(--success); --text-warning: var(--warning); --text-error: var(--error); --text-info: var(--info);
      --surface-success: oklch(from var(--success) calc(l + var(--l-delta-9-down)) calc(c + var(--c-delta-5-down)) h);
      --surface-warning: oklch(from var(--warning) calc(l + var(--l-delta-8-down)) calc(c + var(--c-delta-5-down)) h);
      --surface-error: oklch(from var(--error) calc(l + var(--l-delta-8-down)) calc(c + var(--c-delta-6-down)) h);
      --surface-info: oklch(from var(--info) calc(l + var(--l-delta-8-down)) calc(c + var(--c-delta-5-down)) h);
      --outline-success: oklch(from var(--success) calc(l + var(--l-delta-1)) calc(c + var(--c-delta-1-down)) h);
      --outline-warning: oklch(from var(--warning) calc(l + var(--l-delta-1)) calc(c + var(--c-delta-1-down)) h);
      --outline-error: oklch(from var(--error) calc(l + var(--l-delta-1)) calc(c + var(--c-delta-1-down)) h);
      --outline-info: oklch(from var(--info) calc(l + var(--l-delta-1)) calc(c + var(--c-delta-1-down)) h);
      /* Dark mode specific component roles */
       --scrollbar-thumb-color: var(--outline-overt);
       --scrollbar-track-color: var(--surface-subtle);
       --hr-color: var(--outline-subtle);
       --table-border: var(--outline-default);
       --table-header-bg: var(--surface-subtle);
       --table-row-hover-bg: var(--highlight-bg-subtle);
       --code-block-bg: var(--surface-muted); /* Darker code blocks */
       --code-block-border: var(--outline-subtle);
       --code-inline-bg: var(--surface-muted);
       --code-inline-border: var(--outline-muted);
       --blockquote-border: var(--outline-default);
       
       /* Dark mode shadow adjustments */
       --shadow-color-base: var(--shadow-color-dark);
       --shadow-sm: 0 1px 2px oklch(from hsl(var(--shadow-color-base)) l c h / 10%);
       --shadow-md: 0 4px 6px -1px oklch(from hsl(var(--shadow-color-base)) l c h / 12%), 
                    0 2px 4px -2px oklch(from hsl(var(--shadow-color-base)) l c h / 12%);
       --shadow-lg: 0 10px 15px -3px oklch(from hsl(var(--shadow-color-base)) l c h / 12%), 
                    0 4px 6px -4px oklch(from hsl(var(--shadow-color-base)) l c h / 12%);
       --shadow-xl: 0 20px 25px -5px oklch(from hsl(var(--shadow-color-base)) l c h / 12%), 
                    0 8px 10px -6px oklch(from hsl(var(--shadow-color-base)) l c h / 12%);
       --shadow-inner: inset 0 2px 4px 0 oklch(from hsl(var(--shadow-color-base)) l c h / 7%);
    }
  }
  /* High Contrast Mode Theme */
  @media (prefers-contrast: high) {
    :root { /* High Contrast Light */
      /* Refine existing contrast settings */
      --contrast-factor: 1.3;
      --l-threshold: 0.6;
      --c-threshold: 0.05;
      --surface-c: 0.005;
      
      /* Enhanced focus states */
      --focus-ring-width: 3px;
      --outline-focus: oklch(0.5 0.3 var(--accent-h));
      
      /* Increase border contrast */
      --border-width: 1.5px;
      --border-width-thick: 3px;
      
      /* Enhance text contrast */
      --text-subtle: oklch(0.3 0.03 var(--neutral-h));
      --text-muted: oklch(0.25 0.02 var(--neutral-h));
      
      /* Form elements */
      --outline-overt: oklch(0.4 0.1 var(--accent-h));
      --indicator-color: oklch(0 0 0);
    }
    
    @media (prefers-color-scheme: dark) { /* High Contrast Dark */
      :root {
        --contrast-factor: 1.3;
        --l-threshold: 0.55;
        --c-threshold: 0.05;
        --surface-c: 0.01;
        
        /* Dark-specific high contrast adjustments */
        --text-subtle: oklch(0.85 0.02 var(--neutral-h));
        --text-muted: oklch(0.9 0.01 var(--neutral-h));
        --outline-overt: oklch(0.8 0.1 var(--accent-h));
        --indicator-color: oklch(1 0 0);
      }
    }
    
    /* Enhanced component contrast */
    input, select, textarea {
      border-width: var(--border-width-thick);
    }
    
    input[type="checkbox"], input[type="radio"] {
      border-width: 2px;
    }
  }
  /* Apply Theme Specific Styles */
  html {
    scrollbar-color: var(--scrollbar-thumb-color) var(--scrollbar-track-color);
  }
  ::selection {
    background-color: var(--highlight-bg-overt);
    color: var(--text-on-highlight-overt); /* Requires --bg correctly set or browser calculation */
  }
}


================================================
FILE: src/tokens.css
================================================
/* ================================================ */
/* ==               @layer tokens                == */
/* ================================================ */
@layer tokens {
  /* Register CSS Custom Properties */
  @property --color-h { syntax: '<number>'; inherits: true; initial-value: 250; }
  @property --color-c { syntax: '<number>'; inherits: true; initial-value: 0.1; }
  @property --color-l { syntax: '<percentage>'; inherits: true; initial-value: 50%; }
  @property --color-a { syntax: '<number>'; inherits: true; initial-value: 1; }
  @property --l-threshold { syntax: '<number>'; inherits: true; initial-value: 0.65; }
  @property --c-threshold { syntax: '<number>'; inherits: true; initial-value: 0.08; }
  @property --bg { syntax: '<color>'; inherits: false; initial-value: transparent }
  @property --fg { syntax: '<color>'; inherits: true; initial-value: currentColor; }
  @property --l-delta { syntax: '<percentage>'; inherits: true; initial-value: 0%; }
  @property --c-delta { syntax: '<percentage>'; inherits: true; initial-value: 0%; }

  :root {
    /* ========== COLOR SCALES ========== */
    /* Lightness Scale (0-14) */
    --scale-l-0: 99%; --scale-l-1: 95%; --scale-l-2: 90%; --scale-l-3: 82%;
    --scale-l-4: 74%; --scale-l-5: 66%; --scale-l-6: 58%; --scale-l-7: 50%;
    --scale-l-8: 42%; --scale-l-9: 34%; --scale-l-10: 26%; --scale-l-11: 18%;
    --scale-l-12: 10%; --scale-l-13: 5%; --scale-l-14: 1%;

    /* Chroma Scale (0-12) */
    --scale-c-0: 0; --scale-c-1: 0.02; --scale-c-2: 0.04; --scale-c-3: 0.06;
    --scale-c-4: 0.08; --scale-c-5: 0.1; --scale-c-6: 0.12; --scale-c-7: 0.15;
    --scale-c-8: 0.18; --scale-c-9: 0.22; --scale-c-10: 0.26; --scale-c-11: 0.3;
    --scale-c-12: 0.37;

    /* Alpha Scale (0-8) */
    --alpha-0: 0; --alpha-1: 0.05; --alpha-2: 0.1; --alpha-3: 0.2;
    --alpha-4: 0.4; --alpha-5: 0.6; --alpha-6: 0.75; --alpha-7: 0.9;
    --alpha-8: 1;

    /* Contrast Ratios */
    --contrast-ratio-low: 3; --contrast-ratio-medium: 4.5; --contrast-ratio-high: 7;

    /* Max Chroma per Lightness Band */
    --max-chroma-0: 0.04; --max-chroma-1: 0.08; --max-chroma-2: 0.15;
    --max-chroma-3: 0.22; --max-chroma-4: 0.18; --max-chroma-5: 0.12;
    --max-chroma-6: 0.06;

    /* Base Hue Definitions for Palette */
    --hue-gray: 250; --hue-slate: 215; --hue-red: 25; --hue-orange: 40;
    --hue-amber: 55; --hue-yellow: 90; --hue-lime: 120; --hue-green: 145;
    --hue-emerald: 160; --hue-teal: 180; --hue-cyan: 195; --hue-sky: 210;
    --hue-blue: 245; --hue-indigo: 265; --hue-violet: 285; --hue-purple: 300;
    --hue-fuchsia: 320; --hue-pink: 340; --hue-rose: 355;
    
    /* ========== SHADOW SYSTEM ========== */
    /* Shadow color base using HSL format for easier adjustments */
    --shadow-color-base: 220 10% 10%;
    --shadow-color-dark: 220 20% 90%;
    
    /* Light mode shadows */
    --shadow-sm: 0 1px 2px oklch(from hsl(var(--shadow-color-base)) l c h / 7%);
    --shadow-md: 0 4px 6px -1px oklch(from hsl(var(--shadow-color-base)) l c h / 10%), 
                 0 2px 4px -2px oklch(from hsl(var(--shadow-color-base)) l c h / 10%);
    --shadow-lg: 0 10px 15px -3px oklch(from hsl(var(--shadow-color-base)) l c h / 10%), 
                 0 4px 6px -4px oklch(from hsl(var(--shadow-color-base)) l c h / 10%);
    --shadow-xl: 0 20px 25px -5px oklch(from hsl(var(--shadow-color-base)) l c h / 10%), 
                 0 8px 10px -6px oklch(from hsl(var(--shadow-color-base)) l c h / 10%);
    --shadow-inner: inset 0 2px 4px 0 oklch(from hsl(var(--shadow-color-base)) l c h / 5%);
    
    /* Semantic shadow assignments */
    --shadow-button: var(--shadow-sm);
    --shadow-button-hover: var(--shadow-md);
    --shadow-button-active: var(--shadow-inner);
    --shadow-card: var(--shadow-md);
    --shadow-dropdown: var(--shadow-lg);
    --shadow-modal: var(--shadow-xl);
    
    /* ========== SPACING SYSTEM ========== */
    /* Spacing Scale */
    --spacing-0: 0;
    --spacing-xs: 0.25rem;
    --spacing-sm: 0.5rem;
    --spacing-md: 1rem;
    --spacing-lg: 1.5rem;
    --spacing-xl: 2rem;
    --spacing-2xl: 2.5rem;
    --spacing-3xl: 3rem;
    
    /* ========== TYPOGRAPHY SYSTEM ========== */
    /* Font Size Scale */
    --font-size-xs: 0.75rem;
    --font-size-sm: 0.875rem;
    --font-size-base: 1rem;
    --font-size-lg: 1.125rem;
    --font-size-xl: 1.25rem;
    --font-size-2xl: 1.5rem;
    --font-size-3xl: 1.875rem;
    --font-size-4xl: 2.25rem;
    
    /* Font Weight Scale */
    --font-weight-thin: 100;
    --font-weight-extralight: 200;
    --font-weight-light: 300;
    --font-weight-normal: 400;
    --font-weight-medium: 500;
    --font-weight-semibold: 600;
    --font-weight-bold: 700;
    --font-weight-extrabold: 800;
    --font-weight-black: 900;
    
    /* Line Height Scale */
    --line-height-none: 1;
    --line-height-tight: 1.25;
    --line-height-snug: 1.375;
    --line-height-normal: 1.5;
    --line-height-relaxed: 1.625;
    --line-height-loose: 2;
    
    /* Letter Spacing Scale */
    --letter-spacing-tighter: -0.05em;
    --letter-spacing-tight: -0.025em;
    --letter-spacing-normal: 0;
    --letter-spacing-wide: 0.025em;
    --letter-spacing-wider: 0.05em;
    --letter-spacing-widest: 0.1em;
    
    /* ========== POSITIONING & LAYOUT SYSTEM ========== */
    /* Positioning Scale */
    --inset-0: 0;
    --inset-xs: 0.25rem;
    --inset-sm: 0.5rem;
    --inset-md: 1rem;
    
    /* Z-Index Scale */
    --z-index-0: 0;
    --z-index-10: 10;
    --z-index-20: 20;
    --z-index-30: 30;
    --z-index-40: 40;
    --z-index-50: 50;
    --z-index-auto: auto;
    
    /* Flex Values */
    --flex-1: 1 1 0%;
    --flex-auto: 1 1 auto;
    --flex-initial: 0 1 auto;
    --flex-none: none;
    
    /* Grid Template Sizes */
    --grid-cols-1: repeat(1, minmax(0, 1fr));
    --grid-cols-2: repeat(2, minmax(0, 1fr));
    --grid-cols-3: repeat(3, minmax(0, 1fr));
    --grid-cols-4: repeat(4, minmax(0, 1fr));
    --grid-cols-6: repeat(6, minmax(0, 1fr));
    --grid-cols-12: repeat(12, minmax(0, 1fr));
    
    /* Container Query Breakpoints */
    --cq-bp-xs: 20em;  /* ~320px */
    --cq-bp-sm: 30em;  /* ~480px */
    --cq-bp-md: 45em;  /* ~720px */
    --cq-bp-lg: 60em;  /* ~960px */
    --cq-bp-xl: 80em;  /* ~1280px */
    --cq-bp-2xl: 96em; /* ~1536px */
  }
}


================================================
FILE: test/index.html
================================================
<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>CSS Test</title>
  <link rel="stylesheet" href="../src/index.css">
</head>
<body>
  <style>
    :root {
      --accent-h: 87.2;
      --surface-c: 0.01; 
    }
  </style>
  <nav></nav>
  <main>
    <aside>

    </aside>
    <article>
      <div class="card">

        <div class="btn">
          Submit
        </div>
        <div class="btn-primary">
          Primary
        </div>
      </div>

    </article>
  </main>


  <style>
    nav {
      width: 100%;
      height: 3lh;
      /* background-color: var(--surface-overt-dark); */
      background-color: var(--bedrock);
    }
    main {
      background-color: var(--base);
      width: 100%;
      height: 100%;
      display: flex;
    }

    aside {
      width: 10lh;
      height: 100vh;
      background-color: var(--surface-subtle);
    }

    article {
      margin: 2lh;
      border-radius: 2lh;
      width: 100%;
      /* height: 100%; */
      background-color: var(--surface-overt-light);
      padding: 2lh;
    }

    .btn {
      background-color: var(--surface-overt-dark);
      padding: 10px 25px;
      display: inline-block;
      border-radius: 10px;
    }

    .btn-primary {
      background-color: var(--accent-overt);
      padding: 10px 25px;
      display: inline-block;
      border-radius: 10px;
    }

    .card {
      width: 10lh;
      height: 12lh;
      border-radius: 1lh;
      background-color: var(--surface-default)
    }
  </style>
  
</body>
</html>


================================================
FILE: test/min.css
================================================
@layer reset, tokens, engine, theme, palette, defaults, components, utilities, layouts;

@import url("../src/reset.css");
@import url("../src/engine.css");
@import url("../src/defaults.css");