tailwind-architect
Architect-level Tailwind guidance — token wiring from design tokens into the theme, component-layer boundaries, when utilities are wrong, dark mode and theming strategy, and the class-explosion failure modes that make utility CSS unmaintainable. Use when setting up or auditing a Tailwind codebase.
- License 许可
- MIT
- 最近更新
- 2026-11-13
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- tailwind-architect
- license
- MIT
- metadata
- { "crusor-path": "website-architect/frontend-development-architect/tailwind-architect", "crusor-domain": "website-architect", "crusor-origin": "original", "crusor-sources": "tailwindcss.com/docs; tailwindcss.com/blog/tailwindcss-v4", "crusor-triggers": "tailwind, tailwindcss, utility css, tailwind theme, design tokens, utility classes, tailwind config, design tokens css", "crusor-verified-on": "2026-10-30" }
- description
- Architect-level Tailwind guidance — token wiring from design tokens into the theme, component-layer boundaries, when utilities are wrong, dark mode and theming strategy, and the class-explosion failure modes that make utility CSS unmaintainable. Use when setting up or auditing a Tailwind codebase.
- compatibility
- Tailwind CSS 3.4+/4.x with a token source
03 SKILL.md 正文
Tailwind Architect
Tailwind is a token delivery mechanism, not a styling philosophy. If the theme is arbitrary and the components are long class strings, you have CSS with extra steps.
When to use
- A design system exists or is being defined and must reach the codebase.
- A component library needs consistent spacing/colour/type without a CSS-in-JS runtime.
- Replacing ad-hoc CSS with a constrained scale.
When NOT to use
- Content-heavy documents where semantic CSS is the better abstraction.
- A design system with no tokens — fix the tokens first.
Decision 1 — Tokens are the source of truth
tailwind.config(or@themein v4) maps semantic tokens to utilities:bg-surface,text-muted,border-subtle— notbg-gray-100.- Raw palette values are allowed only in components that are themselves the system (Button variants), never in feature code.
- Light/dark is a token swap (CSS variables), not
dark:scattered through every component.dark:is for exceptions. - Spacing/radius/shadow scales come from the token set; new arbitrary values
(
p-[13px]) are a design decision that must go back into the tokens.
Decision 2 — Where utilities stop
| Layer | Owns |
|---|---|
| tokens | values |
| primitives (Button, Input, Card) | variant API + class composition |
| features | composition and layout only |
- A feature file with 40 classes is a primitive that hasn't been extracted.
- Variants live in
cva/maps inside the primitive, not in call sites. - Conditional class merging goes through one helper (
cn()), never scattered template strings.
Decision 3 — Responsiveness and layout
- Mobile-first breakpoints aligned to real layout shifts, not device names.
- Container queries for component-level responsiveness (cards, panels).
- Grid/flex utilities define layout; components do not carry their own margins (spacing belongs to the parent — the "no external margin" rule).
Decision 4 — Build integration
- Content paths explicit; no dynamic class construction (
bg-${color}-500) — it defeats extraction. Use a safelist or a variant map instead. - CSS variables for theme values that must change at runtime (user theme).
- Purge in production, verified by size budget in CI.
Failure modes at scale
- Every component re-inventing spacing because the tokens are too coarse.
dark:on 300 elements → theme changes are a refactor.- Arbitrary values everywhere → the design system no longer constrains anything.
- Class strings duplicated across features → one visual change, 40 edits.
Verification receipts
- Grep audit: no raw palette utilities in feature files.
bg-${/ dynamic class construction: zero occurrences.- Production CSS size within budget after purge.
- Dark/light switch verified on 3 representative pages.
- A new feature can be built without adding a single arbitrary value.
04 同仓库更多 Skills
interaction-patterns-architect
Architect-level interaction design in code — choosing established patterns over invented ones, feedback and latency behaviour, destructive-action safeguards, navigation and overlay conventions, and the state model behind every interactive surface. Use when a screen has to behave, not just look.
design-system-ops-architect
Architect-level operation of a design system in code — token pipelines and versioning, component API and variant policy, the catalogue as the contract, adoption metrics, and the governance that stops a system from forking into three. Use when a component library must survive several teams.
design-handoff-architect
Architect-level design handoff — what must be specified before implementation starts, tokens over raw values, responsive and content-limit contracts, state matrices, and the review loop that catches drift between design and code. Use when a design is about to become code.
content-microcopy-architect
Architect-level UI content — where strings live, voice and terminology consistency, error and empty-state copy as part of the interface, translation-ready authoring, and the content model a product needs before it multiplies screens. Use when the words in the interface matter as much as the pixels.
ui-ux-implementation-architect
Architect-level direction for turning a design into working UI — the handoff contract, component ownership versus screen-level layout, interaction and state conventions, design QA gates, and the review habits that keep an implementation faithful without frozen pixels. Use before any specific UI implementation skill.
test-strategy-architect
Architect-level test strategy — allocating assertions across unit, integration, contract and end-to-end layers, designing for testability through dependency boundaries, fixture and data strategy, and the flake and coverage policies that keep a suite trustworthy. Use when defining how a codebase is tested.