AGENT SKILL

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 @theme in v4) maps semantic tokens to utilities: bg-surface, text-muted, border-subtle — not bg-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

  1. Grep audit: no raw palette utilities in feature files.
  2. bg-${ / dynamic class construction: zero occurrences.
  3. Production CSS size within budget after purge.
  4. Dark/light switch verified on 3 representative pages.
  5. A new feature can be built without adding a single arbitrary value.

04 同仓库更多 Skills

SriAkhilSJ
SriAkhilSJ/PulseAIRepo

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.

★ 0
SriAkhilSJ
SriAkhilSJ/PulseAIRepo

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.

★ 0
SriAkhilSJ
SriAkhilSJ/PulseAIRepo

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.

★ 0
SriAkhilSJ
SriAkhilSJ/PulseAIRepo

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.

★ 0
SriAkhilSJ
SriAkhilSJ/PulseAIRepo

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.

★ 0
SriAkhilSJ
SriAkhilSJ/PulseAIRepo

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.

★ 0