design-guide
Use when visual/UX design judgment is needed — color palettes, typography, spacing/hierarchy, theme selection, and applying design best practices. Invoke whenever choosing colors or themes, picking st
SKILL.mdskills/design-guide/SKILL.md
GitHubDesign Guide
Goal: make sound visual/UX design decisions and explain them simply, so a design-averse user gets professional-looking results without having to drive the aesthetics.
Workflow
- Read
LEARNINGS.mdbeside this skill, when your copy keeps one, first — it holds the user's recorded preferences and project-specific specs (e.g. a prior screen's filtering UX, partner theming; this install's examples:LOCAL.mdbeside this skill, when your copy keeps one — Recorded specs). A decision that contradicts a recorded preference is a rework, not a judgment call. - Anchor to the app's existing design language. In a Tabler app, lean on Tabler's
palette/spacing/components (see tabler-ui) instead of inventing a parallel language —
consistency beats novelty. For UX shape, check your design system's reference
templates before designing from memory (this install's location:
LOCAL.mdbeside this skill, when your copy keeps one — Reference templates). - Choose colors with the 3-tier method. When no brand palette is given, use the
3-tier color system from Refactoring UI (Wathan & Schoger) as the default toolkit
(this install's worked reference:
LOCAL.mdbeside this skill, when your copy keeps one — Color reference): Primary (look-defining accents, the minority of pixels), Neutrals (tinted grey ramp, ~90% of the UI), Supporting (semantic + extra accents, sparingly). A hue is ~10 shades, not 3; tint the grey to the brand temperature; recipe = 1 primary + 1 grey + 2–4 supporting. Check text/background contrast (WCAG AA). - Apply the standing decisions below — they are settled user preferences, not options to re-litigate.
- When the outcome is hard to predict, render candidates — don't reason in the
abstract. For icon geometry, glyph fit, spacing: build each option as an SVG,
rsvg-convert→ PNG,magick montagethem next to the real existing elements (e.g. sibling icons in the same badge, on the real background), then judge family-fit visually and let the user pick. This caught that a wide glyph never fits a square badge and that a half-scale car blobs at stroke-2 — obvious in render, invisible in code. - Deliver a concrete recommendation (specific colors/values), not a menu — with a one-line rationale. Offer a preview/sample when comparing options.
- Verify in BOTH light and dark mode before showing the result, with inline screenshots — theme-dependent contrast failures are an established bug class here.
Standing decisions (apply by default; recorded user preferences)
- Status color semantics are fixed: success = green, failed/error = red,
partial/in-between = amber/yellow, skipped/neutral = grey. Render statuses in tables as
colored pills/badges in a soft/muted tone (the opaque
bg-*-subtle+text-*-emphasispair; Tabler's-lttints fail AA contrast, see tabler-ui's layout-visuals.md), never loud full-saturation, never plain text — soft pills stay readable in dense tables. - Never use color alone to convey state — pair it with text or an icon (a red pill also reads "Failed"), so state survives color-blindness and greyscale.
- Semantic colors stay consistent app-wide (success/warn/danger/info); validation
feedback is red (
text-danger/.invalid-feedback). - Destructive actions always confirm: every delete/remove opens a warning-styled dialog with a danger-colored confirm button first — the danger must be visible before the click, never delete-on-click.
- No silent failures into empty states: a failed action must surface an error (e.g. a toast); a swallowed failure renders a misleading "no data" view indistinguishable from genuinely having no data.
- Date vs. datetime: show date-only for date-semantic fields (billing-period boundaries, from–to ranges); reserve full timestamps for true event times (created/updated/started/ended) — precision that carries no meaning is noise.
- DRY look-and-feel: the user dislikes re-styled one-off patterns — prefer one generic, metadata-driven component (e.g. the data table) so sorting/filtering/styling stay uniform everywhere.
- Hero eyebrow/kicker hierarchy: a kicker above a hero title must be visually smaller
than the title and separated by vertical spacing — at the same size it competes with
the headline and flattens the hierarchy. (Tabler values:
fs-2 fw-semibold mb-3 text-primaryvs a 3rem.hero-title— see tabler-ui. Where these values were measured:LOCAL.mdbeside this skill, when your copy keeps one — Hero kicker values.) - Brand lead-in punctuation: a primary-colored brand lead-in followed by a
descriptive phrase reads as one sentence only as "Brand: lowercase continuation"
("Acme: powering your next project…"); two capitalized fragments read as a collision.
(This install's original example:
LOCAL.mdbeside this skill, when your copy keeps one — Brand lead-in example.) - Custom icons must match the set's design language exactly (Tabler: 24×24 grid, stroke-2, real primitives) — a free-handed one-off reads as foreign next to siblings. For a two-concept icon, balance both parts at comparable size; a tiny corner badge subordinates one concept (user rejected exactly this). Build/verify details: tabler-ui layout-visuals.md.
- Typography: generous, consistent sizing — stakeholders repeatedly flag small body copy. Align to the app's existing type scale (Tabler marketing scale) rather than arbitrary px; body/section descriptions ≥ 1rem.
Common failure modes
- Guessing visual outcomes in code instead of rendering candidates (step 5) — icon fit, glyph scale, and spacing judgments made abstractly get rejected on sight.
- Inventing a new palette/pattern inside an app with an established language — extend Tabler's tokens and existing components; novelty here reads as inconsistency.
- Full-saturation status colors or plain-text statuses in tables — violates the fixed soft-pill rule above.
- Checking only light mode — contrast and hardcoded-color failures surface in dark
mode (e.g. a third-party sign-in button rendering white-on-white until wrapped in
color-scheme: light; the originating ticket:LOCAL.mdbeside this skill, when your copy keeps one — Dark-mode sign-in button). - Designing at English length only — in a multi-language product, labels run 30–40% longer and RTL mirrors the layout; judge the design in the longest locale and in RTL (i18n §8 and its pseudo-locale sweep).
- Offering the user a menu of options with no recommendation — the user is design-averse; decide, recommend one, explain in a line.
Before you call this done
- Read
LEARNINGS.md(when your copy keeps one); no recorded preference contradicted. - Consistent with the app's existing design language (and your design system's reference templates where UX shape was involved).
- Status/semantic colors follow the fixed mapping; contrast meets WCAG AA.
- Hard-to-predict visuals were rendered and compared, not guessed.
- Verified in BOTH light and dark mode; inline screenshots shared.
- Delivered a concrete recommendation with a one-line rationale.
Capturing learnings (session-handoff protocol)
Accumulate design preferences and good references in LEARNINGS.md beside this skill,
when your copy keeps one. On
handoff / "update skills" / after design work: record palettes/themes chosen (hex values +
roles), the user's likes/dislikes (and why a liked product's look works — palette,
density, hierarchy, motion), and reusable best-practice notes. Dedupe/merge, tag where
project-specific. Promote settled, general rules into the "Standing decisions" list above
(leave a pointer in LEARNINGS). Read LEARNINGS before design decisions.