asw/content/docs/tokens.md

title	description	type	weight	date	tags	ai-disclosure	ai-model	ai-provider
Token System	How ASW's CSS custom property hierarchy is structured — Open Props base, semantic aliases, and component tokens.	docs	20	2026-04-09	tokens css reference	generated	claude-sonnet-4-5	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.

/* 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:

: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.

: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:

@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.

/* 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.

/* 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

--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:

--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) */