Code-Society-Lab / Code-Society-Lab/matrix-directory

Refactor theme tokens into semantic Tailwind utilities

Open
#22 0 comments 0 reactions 0 assignees View on GitHub
enhancement frontend good first issue
Dominant language
Python
Stars
5
Forks
0
Avg merge
3h
Merged PRs (30d)
28

Description

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

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

should become:

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

```css
@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:

```html
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
```

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.