PW Pathway

Styling

Overview of the CSS architecture and theming system in Pathway.

Pathway uses a token-based CSS architecture with layered overrides, designed to be both AI-friendly and human-editable.

CSS Cascade Order

Styles are loaded in this order, with later files overriding earlier ones:

  1. src/styles/global.css — Tailwind + app shell styles
  2. src/themes/default.css — Base design tokens + block recipes
  3. src/themes/*.css — Theme token overrides (scoped to [data-theme])
  4. src/content/templates/*.css — Template-specific decorations (scoped to [data-template])
  5. src/content/project.css — Project-level overrides

Design Tokens

Tokens are CSS custom properties defined in theme files. They cover:

  • Colors: --color-bg, --color-surface, --color-accent, --color-text, etc.
  • Typography: --font-sans, --font-heading, --text-sm, --text-2xl, etc.
  • Spacing: --space-1 through --space-16
  • Radii: --radius-sm, --radius-md, --radius-lg, etc.
  • Shadows: --shadow-sm, --shadow-md, --shadow-glow
  • Transitions: --transition-fast, --transition-base

Block Recipes

Block recipes in default.css define how each block kind looks using tokens:

[data-block-kind="heading"] {
  font-family: var(--font-heading);
  font-size: var(--text-2xl);
  color: var(--color-text);
}

[data-block-kind="button"][data-style="primary"] {
  background: var(--color-accent);
  color: var(--color-accent-text);
}

Themes

Themes override tokens for a different visual identity. They are scoped via [data-theme="..."]:

[data-theme="avionics"] {
  --color-bg: oklch(98% 0.005 240);
  --color-accent: oklch(50% 0.2 250);
  --radius-md: 0;
}

Templates declare their theme in JSON:

{
  "id": "avionics",
  "theme": "avionics",
  "blocks": [...]
}

Template Decorations

Template CSS files add visual elements specific to a template (backgrounds, labels, etc.):

[data-template="avionics"] {
  background-image: linear-gradient(...);
}

[data-template="avionics"]::before {
  content: "SPEC";
  /* corner label styling */
}

Project Overrides

src/content/project.css allows project-specific customizations:

/* Override accent color for this project */
[data-theme="avionics"] {
  --color-accent: oklch(55% 0.2 280);
}

/* Style a specific block */
[data-block-id="intro-card"] {
  border-width: 2px;
}

Data Attributes

Blocks emit these attributes for CSS targeting:

  • data-block-kind — Block type (e.g., "heading", "button")
  • data-block-id — Unique block ID
  • data-style — Block variant (e.g., "primary", "secondary")
  • data-clickable — Present if block has click events
  • data-template — Template ID (on container)
  • data-theme — Theme ID (on container)