AGENTS.md · git:20261112.3a243ef · 2026-11-12 · sha256 094e37c748d9a1f8

AGENTS.md git:20261112.3a243efA

Immutable. This exact content never changes and is served at /api/v1/blob/094e37c748d9a1f8.

# AGENTS.md: how to build with the Liquid Glass Design System

Liquid Glass Design System by [Tammo Elsner](https://www.linkedin.com/in/tammo-elsner-682998186/), MIT. Read this file before every change. The visual rules are in `DESIGN.md`; exact component specs in `docs/COMPONENTS.md`.

## Golden rule

The design system (`src/styles/lg-*.css`, `src/components/lg/*`, `src/lib/cn.ts`) is the approved reference. Never restyle, rewrite or "improve" it inside a page. Change behavior only by extending a primitive for the whole project, then document it in `DESIGN.md` and show it on the styleguide.

## Install into an existing React + Tailwind v4 project

Fastest: `npx skills add tammo1007/liquid-glass-design-system`, then `node .claude/skills/liquid-glass-design-system/scripts/install.mjs` (adapt the folder to your agent). It copies every file below and prints the remaining steps. By hand:

1. Copy `src/styles/` (lg-tokens.css, lg-tailwind.css, lg-product.css, lg-scroll.css), `src/components/lg/` and `src/lib/cn.ts`.
2. `npm i motion lenis clsx tailwind-merge class-variance-authority @radix-ui/react-slot @heroicons/react @fontsource-variable/inter`
3. In your main CSS, in this order:
   ```css
   @import "tailwindcss";
   @import "@fontsource-variable/inter";
   @import "./styles/lg-tokens.css";
   @import "./styles/lg-tailwind.css";
   @import "./styles/lg-product.css";
   @import "./styles/lg-scroll.css";
   ```
4. Path alias `@/*` → `src/*`. Wrap the app in `<SmoothScroll>`. With a router, wrap it once in `<LinkAdapterProvider component={({ href, ...p }) => <Link to={href} {...p} />}>`.
5. Copy `DESIGN.md`, `AGENTS.md`, `docs/COMPONENTS.md` and `scripts/lg-audit.mjs` into the project. Add `"audit": "node scripts/lg-audit.mjs"` to package.json.
6. Theme: set `data-theme="light|dark"` on `<html>` before first paint (see the inline script in `index.html`).

## File map

| Path | What it is | May pages edit it? |
|---|---|---|
| `DESIGN.md` | Tokens (front matter) and every rule | Only when the system changes |
| `docs/COMPONENTS.md` | Exact specs of every primitive | Only when the system changes |
| `src/styles/lg-tokens.css` | All raw values: color (light, dark, increased contrast), type, layout, shape, motion, glass and base primitives | No, system changes only |
| `src/styles/lg-tailwind.css` | Token → Tailwind v4 classes (`@theme`) | System changes only |
| `src/styles/lg-product.css` | App shell, sidebar, toolbar, tab bar, tables, badges, controls, menus | System changes only |
| `src/styles/lg-scroll.css` | Pinned stages and scroll primitives | System changes only |
| `src/components/lg/*` | Primitives, barrel `@/components/lg` | System changes only |
| `src/components/lg/icons.tsx` | Heroicons wrapper (stroke 1.35 / 1.5), the only icon source | Add icons here |
| `src/lib/cn.ts` | `cn()` with tailwind-merge that knows every token class | System changes only |
| `tokens/tokens.json` | W3C DTCG tokens, generated by `npm run tokens` | Never by hand |
| `scripts/lg-audit.mjs` | Static checker, fails on drift | |
| `src/demo/*` | Landing, dashboard and styleguide demos | Yes (examples) |

## How to build a marketing page

1. Pick the recipe in `DESIGN.md` §9 (landing or subpage).
2. Wrapper `<div className="lg-root flow-root">`. Landing: `<DockNav>` as first child, then `<main>`. Subpages: `<GlassNav>`, first `<Section spacing="sm" offsetNav>` or `<PageHero>`.
3. Compose: `<Section tone spacing>` → `<Container size>` → `<SectionHeader title titleMuted>` → content from `Tile`, `MediaCard`, `FeatureItem`, `Stat`, `ArrowLink`, `Button`, `CardRail`/`RailCard`, `AccordionShowcase`, `FaqList`, `PricingTier`, scroll showpieces.
4. Every landing page has exactly one `CardRail` section with 6 to 9 `RailCard`s whose visuals are product UI rebuilt in HTML.
5. Scroll: max 3 pinned showpieces (`MediaExpand`, `ZoomThrough`, `StackCards`, `PinnedGallery`, `ScrollStory`), never first, never adjacent.
6. Links: `<SmartLink href>` with URLs from one `site.ts`-style config. Buttons as links: `<Button asChild><SmartLink href>…</SmartLink></Button>`.

## How to build a product page (dashboard, admin, settings)

1. `<AppShell brand nav currentHref footer>` → `<Toolbar title subtitle center actions>` → `<AppContent>`.
2. Only `text-ui-*` classes. Never `text-h*`, `text-lead`, `text-display`, `Section`, `Tile`, `SectionHeader` inside AppShell.
3. Content in `UICard`s on `gap-app-gap` grids. KPIs with `Metric`, charts with `LineChart` / `BarChart` / `BarList` (always a `summary`), lists with `DataTable` inside `<UICard padded={false}>`.
4. Toolbar: max 3 `ToolbarGroup`s (icons OR text), then one `<Button variant="accent" size="ui">`. Other buttons in products use `size="ui"` or `xs`.
5. Details in a `Sheet`, confirmations in a `Dialog`, feedback via `useToast()` (wrap the page in `ToastProvider`).
6. Status always as `Badge` with a word. Deltas with `trend` so good and bad are explicit.

## Definition of Done (check every item after every change)

- [ ] Only `@/components/lg` primitives and token classes. No hex/rgb in code, no palette colors (`gray-*`, `blue-*`), no arbitrary values for type, spacing, radius, shadow or z, no visual inline styles.
- [ ] No default Tailwind sizes (`text-sm`, `text-xl`) or radii (`rounded-lg`). Headings never bold.
- [ ] The right scale: marketing classes on websites, `text-ui-*` inside AppShell.
- [ ] One `h1` per page, every section opens with an `h2` (`sr-only` if invisible), cards/steps/FAQ questions are `h3`.
- [ ] Section headers left-aligned two-tone (center only hero variant and final CTA). Chrome monochrome; the accent marks at most one prominent action per view.
- [ ] Glass only on navigation and controls. No glass on cards, no glass on glass.
- [ ] Landing page: one CardRail present. Max 3 pinned scroll sections, not first, not adjacent.
- [ ] Width via `Container` (or `AppContent`), rhythm via `Section spacing`. Grids declare `grid-cols-1` as base.
- [ ] Max 2 dark sections on a light page, not first, not adjacent.
- [ ] Icons: Heroicons via `Icons` only, every icon-only control has an `aria-label`.
- [ ] Every phone/window inside `DeviceStage` or `FloatingDevice`.
- [ ] Class names are complete literal strings (never `` `lg-x--${v}` ``; map variants to full strings).
- [ ] Checked at 390 px and 1440 px in light AND dark: no horizontal scroll, nothing clipped, touch targets 44 px.
- [ ] Reduced motion respected, nothing hidden before hydration, no `window`/`document` during render.
- [ ] No `[LG]` warnings or errors in the console. `npm run audit` passes.

## Never

- Rewrite, restyle or "simplify" files in `src/components/lg` or `src/styles` from a page.
- Centered content-section headers, badge pills above the hero H1, bold headlines, colored eyebrows, gradient text or buttons, glass cards, icons in colored blobs, emoji, sparkle icons, fake logos, placeholder quotes.
- Any icon set other than Heroicons. Any animation library other than `motion/react` and `lenis` (no GSAP, AOS, framer-motion imports, Locomotive).
- Embed SF Pro files or load Google Fonts.
- `100vh` / `h-screen` (use `svh`/`dvh`), `maximum-scale=1`, `user-scalable=no`.
- Animate `backdrop-filter`, width, height, top or left.
- Build your own floating nav, footer, sidebar, toolbar or horizontal scroller. Use `DockNav`, `GlassNav`, `AppShell`, `Toolbar`, `CardRail`.
- Use `accent` (#0088FF) for small text. Text, links and focus use `accent-strong`; filled buttons use `accent-fill`.
- Copy-paste a primitive into a page to tweak it. Extend the primitive instead.

## When a request conflicts with the system

Say so in one sentence, propose the closest system-conform solution, and ask whether to (a) use that, (b) extend the system, or (c) make a documented one-off exception with an `// lg-audit-ignore: reason` comment.