LLMSkillHub
mirroredCopied from nahid-sparktales/agent-dispatcher under MIT. nahid-sparktales has not claimed this page, and is not affiliated with LLM SkillHub.

nahid-sparktales / tailwind

Work inside an existing Tailwind codebase without degrading it — use the project's theme tokens instead of arbitrary values, extend the theme when a token is genuinely missing, extract repetition into components rather than @apply, resolve class conflicts with the project's merge helper, and make dark mode a token decision. Fires when writing or editing Tailwind classes in a repo that already uses it. Not for deciding whether to adopt Tailwind, not for visual design direction, and not a rendered-output check.

0
SKILL.md
5.6 KB

Tailwind

A Tailwind codebase degrades one arbitrary value at a time. Every value you hardcode is a design
decision the theme can no longer make.

When this fires

Writing or editing Tailwind utility classes in a project that already uses Tailwind. It does not
fire for choosing a styling approach, for visual design direction, or for CSS in a project that
does not use Tailwind.

Procedure

  1. Read the theme before writing a class. Tailwind's major versions place theme configuration
    differently — a JS/TS config file in some, a CSS-side theme block in others — so find where
    this project defines its tokens (and confirm the version from the lockfile; see
    stack-detection). Read the colors, spacing, radius, font and breakpoint tokens that exist.

  2. Read one or two existing components in the same area. The class vocabulary a team actually
    uses is a stronger constraint than what Tailwind permits.

  3. Reach for a token before a value. Semantic color tokens over raw palette steps, scale
    spacing over pixel values. If you are about to type a bracketed arbitrary value, first check
    whether a token covers it.

  4. When no token covers it, add the token — do not sprinkle the value. Ask whether this is a
    one-off (one arbitrary value, with a comment saying why) or a design decision (belongs in the
    theme). Adding a theme token changes the whole app's vocabulary, so say what you are adding and
    why in the report.

  5. Do not extract on the second repetition. Two similar class lists are cheaper than a wrong
    abstraction. At the third, extract a component — the props and boundaries question is
    component-architecture, not a CSS question. Reserve @apply for a genuinely global primitive
    in the stylesheet; an @apply block that reimplements a component is worse than the repetition.

  6. Merge conditional classes with the project's helper. Later position in the class string
    does not win a conflict — the generated stylesheet's order decides, so p-2 and p-4 in
    one string resolve unpredictably. Use the project's existing cn/merge utility for any
    conditional or overridable class, and pass overrides through it rather than concatenating.

  7. Never build a class name from a fragment. Tailwind finds classes by scanning source text,
    so bg-${color}-500 produces no CSS. Write full class strings in a lookup map, and confirm the
    file you are editing is inside the project's content/source scan paths — a class in an
    unscanned file silently produces nothing.

  8. Make dark mode a token decision, not a per-utility one. Check the project's dark-mode
    strategy first (media query vs a class/attribute toggle) and follow it. Prefer semantic tokens
    whose values differ per theme over stacking a dark: variant on every utility; add dark:
    where the token system genuinely cannot express the difference.

  9. Keep the class order the project keeps. If a class-sorting formatter is configured, run the
    project's format command rather than hand-sorting.

  10. Look at it in both themes and at the breakpoints you touched. Class lists are not evidence
    of rendering; hand that off to browser-verification.

Checklist

  • [ ] Theme tokens read before classes were written
  • [ ] No arbitrary value that an existing token covers
  • [ ] Any new token added to the theme, with the reason stated
  • [ ] Repetition extracted at the third occurrence, as a component
  • [ ] @apply used only for a global primitive, if at all
  • [ ] Conditional/override classes routed through the project's merge helper
  • [ ] No class name assembled from fragments
  • [ ] Dark mode expressed through tokens where the system allows it
  • [ ] Project formatter run; class order matches the codebase
  • [ ] Light and dark rendered and looked at, not inferred

Failure handling

  • A class is in the source but no style appears — check, in order: the file is inside the scan
    paths, the class name is a complete literal string, the utility actually exists in this major
    version, and the build was re-run.

  • A style applies but the wrong value wins — a conflict, not a specificity puzzle. Route both
    classes through the merge helper instead of adding !important.

  • Dark mode is right in one place and wrong in another — the two places are using different
    mechanisms (one token, one dark: variant). Unify on the project's strategy.

  • A design needs a value no token has and the theme owner is not you — use one arbitrary value
    with a comment and raise the missing token. Do not add tokens to a shared theme unasked; that is
    a change to every screen.

  • A theme token's value needs changing — that repaints the app. Stop and ask before editing an
    existing token's value, even when it looks obviously wrong.

Evidence to report

The tokens used; any token added, with its file and the reason; the count of arbitrary values left
and why each survived; whether repetition was extracted or deliberately left; and confirmation that
light and dark were both rendered, or a plain statement that they were not.