Vigilio Desto
da1d02ccd1
- content/vault/: _index.md, diff.md, session.md, status.md, tasks.md, wikilinks.md - content/docs/: _index.md, introduction, tokens, reset, semantic-html, components, data-attributes, navigation, layouts, charts, chroma, accordion-dialog 96 pages build clean (was 36). Docs use sidebar nav + TOC layout. Vault uses sidebar with section fallback (no vault menu configured yet). URLs fixed: playground refs → asw.trentuna.com. Closes: asw#12, asw#9
156 lines
4.2 KiB
Markdown
156 lines
4.2 KiB
Markdown
---
|
|
title: "Token System"
|
|
description: "How ASW's CSS custom property hierarchy is structured — Open Props base, semantic aliases, and component tokens."
|
|
type: docs
|
|
weight: 20
|
|
date: 2026-04-09
|
|
tags: ["tokens", "css", "reference"]
|
|
ai-disclosure: "generated"
|
|
ai-model: "claude-sonnet-4-5"
|
|
ai-provider: "Anthropic"
|
|
|
|
---
|
|
|
|
## Overview
|
|
|
|
ASW uses a three-layer token hierarchy built on Open Props. Each layer is additive: base palette → semantic aliases → component-specific values.
|
|
|
|
```
|
|
Open Props palette → ASW semantic aliases → component tokens
|
|
--gray-5 --text-2 --input-border
|
|
--green-5 --accent --callout-info
|
|
--blue-5 --link --task-done
|
|
```
|
|
|
|
No layer can break the others. Override a semantic alias, and every component that references it updates.
|
|
|
|
## Layer 1 — Open Props palette
|
|
|
|
ASW inlines the Open Props token set directly — no CDN dependency. The full color palette (`--gray-0` through `--gray-15`, plus hue families), spacing scale, font stacks, and easing curves are all available.
|
|
|
|
```css
|
|
/* These are defined for you — do not redeclare them */
|
|
--gray-0: oklch(99% 0.005 var(--gray-hue));
|
|
--gray-15: oklch(10% 0.005 var(--gray-hue));
|
|
--green-5: #51cf66;
|
|
--blue-5: #339af0;
|
|
```
|
|
|
|
One knob controls the entire gray family:
|
|
|
|
```css
|
|
:root {
|
|
--gray-hue: 150; /* default: subtle green tint */
|
|
}
|
|
```
|
|
|
|
Change `--gray-hue` to `45` for warm stone, `220` for cool blue-gray, `0` for neutral.
|
|
|
|
## Layer 2 — Semantic aliases
|
|
|
|
Defined in `:root`, these translate palette values to intent. These are the tokens you override to theme a site.
|
|
|
|
```css
|
|
:root {
|
|
/* Surfaces */
|
|
--surface: var(--gray-15); /* page background */
|
|
--surface-1: var(--gray-14); /* cards, sidebars */
|
|
--surface-2: var(--gray-13); /* hover, raised */
|
|
|
|
/* Text */
|
|
--text: var(--gray-1); /* primary */
|
|
--text-2: var(--gray-3); /* secondary */
|
|
--text-3: var(--gray-5); /* muted */
|
|
|
|
/* Accent */
|
|
--accent: var(--green-5);
|
|
--accent-hover: var(--green-4);
|
|
--on-accent: var(--gray-15);
|
|
|
|
/* Links */
|
|
--link: var(--blue-5);
|
|
--link-hover: var(--blue-4);
|
|
|
|
/* Border */
|
|
--border: var(--gray-11);
|
|
--border-subtle: var(--gray-12);
|
|
}
|
|
```
|
|
|
|
Light mode overrides the same tokens:
|
|
|
|
```css
|
|
@media (prefers-color-scheme: light) {
|
|
:root {
|
|
--surface: var(--gray-0);
|
|
--text: var(--gray-14);
|
|
--accent: var(--green-8);
|
|
}
|
|
}
|
|
```
|
|
|
|
## Layer 3 — Component tokens
|
|
|
|
Component tokens are semantic aliases scoped to specific UI patterns. They reference Layer 2 tokens rather than the palette directly.
|
|
|
|
```css
|
|
/* Agent-native tokens */
|
|
--task-done: var(--green-5);
|
|
--task-wip: var(--yellow-5);
|
|
--task-blocked: var(--red-5);
|
|
--task-todo: var(--gray-5);
|
|
|
|
--callout-info: var(--blue-5);
|
|
--callout-warn: var(--yellow-5);
|
|
--callout-error: var(--red-5);
|
|
--callout-note: var(--gray-5);
|
|
|
|
/* Session / vault */
|
|
--session-bg: var(--surface-1);
|
|
--wikilink: var(--blue-4);
|
|
--redacted: var(--gray-8);
|
|
```
|
|
|
|
## Theming a site
|
|
|
|
To rebrand: override semantic aliases only. Never override the Open Props palette.
|
|
|
|
```css
|
|
/* your-theme.css — load after agentic.css */
|
|
:root {
|
|
--gray-hue: 220; /* cool blue-gray neutrals */
|
|
--accent: var(--violet-5);
|
|
--link: var(--violet-4);
|
|
}
|
|
```
|
|
|
|
That is the entire theme file. Surfaces, borders, focus rings, callouts, and task states all update from those three lines.
|
|
|
|
## Typography scale
|
|
|
|
```css
|
|
--text-xs: 0.75rem; /* badges, fine print */
|
|
--text-sm: 0.875rem; /* metadata, captions */
|
|
--text-base: 1rem; /* body text */
|
|
--text-2xl: 1.5rem; /* subheadings */
|
|
--text-3xl: 2rem; /* section headings */
|
|
|
|
/* Heading sizes */
|
|
--h1-size: 1.875rem;
|
|
--h2-size: 1.5rem;
|
|
--h3-size: 1.25rem;
|
|
```
|
|
|
|
## Spacing scale
|
|
|
|
Aliased from Open Props sizes, with one gap filled:
|
|
|
|
```css
|
|
--space-1: 0.25rem; /* var(--size-1) */
|
|
--space-2: 0.50rem; /* var(--size-2) */
|
|
--space-3: 0.75rem; /* no OP equivalent — defined by ASW */
|
|
--space-4: 1.00rem; /* var(--size-3) */
|
|
--space-5: 1.50rem; /* var(--size-5) */
|
|
--space-6: 2.00rem; /* var(--size-7) */
|
|
--space-8: 4.00rem; /* var(--size-9) */
|
|
```
|