Skip to content

Refactor theme tokens into semantic Tailwind utilities #22

Description

@chrisdedman

Description

Refactor the existing CSS variable-based design system so components can use semantic Tailwind color utilities instead of direct var(...) references.

This should improve readability and make future theme work easier.

For example:

class="bg-[var(--surface)] text-[var(--text)] border-[var(--border)]"

should become:

class="bg-surface text-text border-border"

Acceptance criteria

  • Existing design tokens are exposed through Tailwind using @theme inline
  • Semantic utilities exist for backgrounds, text, borders, muted states, and accent colors
  • Components use semantic Tailwind utilities instead of direct CSS variable references where practical
  • Existing light theme appearance remains unchanged
  • No dark mode behavior is introduced as part of this issue

Implementation notes

Map the existing CSS variables to Tailwind semantic color tokens:

@theme inline {
  --color-background: var(--bg);
  --color-surface: var(--surface);
  --color-sunk: var(--sunk);
  --color-hover: var(--hover);

  --color-border: var(--border);
  --color-border-strong: var(--border-strong);

  --color-text: var(--text);
  --color-muted: var(--muted);
  --color-faint: var(--faint);

  --color-accent: var(--accent);
  --color-accent-deep: var(--accent-deep);
  --color-accent-soft: var(--accent-soft);
  --color-accent-ink: var(--accent-ink);
}

Components should then use utilities such as:

bg-background
bg-surface
bg-sunk
bg-hover

text-text
text-muted
text-faint

border-border
border-border-strong

bg-accent
bg-accent-soft
text-accent-ink

Metadata

Metadata

Assignees

No one assigned

    Labels

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions