# CSS Scaffolding Guide
This guide covers CSS implementation for Decantr projects.
---
## Quick Start
Decantr's CSS system has two parts:
1. **@decantr/css** - Runtime atoms for layout utilities (`_flex`, `_gap4`, etc.)
2. **Generated CSS files** - Theme tokens and visual treatments created by `decantr init`
### Setup
```javascript
// 1. Install the atoms runtime
npm install @decantr/css
// 2. Import in your entry point
import { css } from '@decantr/css';
import './styles/tokens.css'; // Generated by decantr init
import './styles/treatments.css'; // Generated by decantr init (visual treatments)
import './styles/decorators.css'; // Generated by decantr init (theme decorators)
```
### Runtime Rules
- Use the real `@decantr/css` runtime for atoms. If `package.json` does not already include `@decantr/css`, add it before building.
- Do **not** create local atom-runtime substitutes such as `src/lib/css.js`, `src/lib/css.ts`, or hand-written `src/styles/atoms.css` files unless you are intentionally running in an explicit fallback mode.
- Treatments are semantic base behavior. Decorators are additive theme-specific augmentation. For example, use `d-control` as the default input treatment and layer a decorator like `carbon-input` only when the contract explicitly asks for it.
- Loading decorators such as `carbon-skeleton` enhance a real loading state; they do not replace the need for explicit loading/skeleton branches in the UI.
### Usage
```jsx
// Layout atoms processed at runtime
// Responsive prefixes (mobile-first: sm=640px, md=768px, lg=1024px, xl=1280px)
{/* 1 col -> 2 cols -> 4 cols */}
// Pseudo-class prefixes
Hover me
```
### Common Atoms
| Category | Atoms |
|----------|-------|
| Display | `_flex`, `_grid`, `_block`, `_inline`, `_none` |
| Flexbox | `_col`, `_row`, `_wrap`, `_flex1`, `_grow`, `_shrink0` |
| Alignment | `_aic`, `_jcc`, `_jcsb`, `_ais`, `_jcfs` |
| Spacing | `_gap{n}`, `_p{n}`, `_m{n}`, `_pt{n}`, `_px{n}`, `_my{n}` |
| Sizing | `_wfull`, `_hfull`, `_w{n}`, `_h{n}`, `_minw0`, `_maxwfull` |
| Typography | `_textsm`, `_textlg`, `_heading1`-`_heading6`, `_fontbold` |
| Colors | `_bgprimary`, `_bgsurface`, `_fgmuted`, `_bcborder` |
| Grid | `_gc{n}`, `_span{n}`, `_colstart{n}` |
### HTML Setup
```html
Skip to content `.
- Pair that skip link with a real main landmark target such as ``.
- Always include a `prefers-reduced-motion: reduce` path in project CSS when the Decantr contract requires reduced motion.
### SEO Expectations by Platform
- For hash-routed SPA scaffolds, keep SEO expectations focused on the root document: title, description, share metadata, and any root-level JSON-LD required by the contract.
- Do **not** invent SSR-style per-route metadata systems for a clearly hash-routed project.
- For history/SSR-style projects, richer route metadata is appropriate, but it still needs to stay aligned with the declared route contract.
### Complex Pattern Rule
- When a pattern implies advanced interaction depth (for example minimaps, drag/drop, force-directed layout, or live streaming), implement the required structure and states first.
- Treat those richer capabilities as optional scaffold-tier enhancement unless the section/page pack explicitly makes them mandatory.
---
## Advanced: Manual CSS Implementation
The following sections cover manual CSS implementation for advanced scenarios where @decantr/css isn't sufficient.
---
## Layer Structure (Mandatory)
All Decantr projects **must** declare CSS `@layer` order for deterministic cascade control. This is not optional -- omitting layers causes specificity conflicts between treatments, decorators, and app styles.
```css
@layer decantr.reset, decantr.tokens, decantr.treatments, decantr.decorators, decantr.patterns, decantr.utilities, app;
@layer decantr.reset {
*, *::before, *::after { box-sizing: border-box; }
body { margin: 0; }
}
@layer decantr.tokens {
:root {
/* Theme seed colors */
--d-primary: #FE4474;
--d-secondary: #0AF3EB;
--d-accent: #FDA303;
--d-bg: #0D0D1A;
/* Spacing tokens */
--gap1: 4px;
--gap2: 8px;
--gap3: 12px;
--gap4: 16px;
--gap6: 24px;
--gap8: 32px;
--gap12: 48px;
}
}
@layer decantr.treatments {
/* Base visual treatments (6 categories) */
.d-interactive { /* buttons, links, clickable cards */ }
.d-surface { /* container panels, cards, modals */ }
.d-data { /* tables, lists, data grids */ }
.d-control { /* form inputs, selects, textareas */ }
.d-section { /* section rhythm and spacing */ }
.d-annotation { /* badges, tags, status indicators */ }
}
@layer decantr.decorators {
/* Theme-specific decorator classes (Layer 3) */
.lum-glass { /* ... */ }
.lum-orbs { /* ... */ }
}
@layer decantr.patterns {
/* Pattern base styles */
.pattern-hero { /* ... */ }
.pattern-kpi-grid { /* ... */ }
}
@layer decantr.utilities {
.d-flex { display: flex; }
.d-grid { display: grid; }
}
@layer app {
/* Application-specific overrides */
}
```
---
## Theme Scoping on HTML Tag
**The HTML element MUST have theme and mode attributes for proper scoping:**
```html
{{PROJECT_NAME}}