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

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions