stolinski/s-stack/graffiti-best-practices

Graffiti Best Practices

Generate high-quality Graffiti markup using current library constraints.

Graffiti is the baseline design layer when this skill is active: it provides the default system for elements, layout primitives, utilities, components, and color/theme tokens.

This skill extends Graffiti patterns; it does not create a parallel styling system.

This skill is strict about class-first composition, minimal inline style usage, semantic HTML, and repeatable quality checks.

It is also strict about template-first adaptation: when a matching hosted template baseline exists, start from that template and customize it.

Quality bar: passing the markup contract is necessary but not sufficient. Output must also clear an aesthetic bar (voice, density, imagery, restraint). Markup that satisfies every contract check but ships with AI-shaped content (generic copy, decorative gradients, invented SVG icons, fake numbers, emoji-as-icons) still fails. See references/AESTHETIC_GUIDE.md.

Audience: developers using Graffiti in real applications and websites.

Package Structure

• SKILL.md - activation rules, boundaries, and execution workflow
• references/OUTPUT_CONTRACT.md - required response structure and scoring gates
• references/GRAFFITI_SYSTEM.md - Graffiti identity, token/variable model, and source-of-truth lookup rules
• references/COMPONENT_INTENT_MATRIX.md - role boundaries for core components (use-when, do-not-use, fallback)
• references/CANONICAL_SNIPPETS.md - critical pattern snippets that must be used as first-choice baselines
• references/RECIPES_LAYOUTS.md - page shell and layout recipes
• references/RECIPES_SECTIONS.md - section-level recipes by intent
• references/RECIPES_COMPONENTS.md - component-level recipe snippets
• references/ANTI_PATTERNS.md - failure mode catalog and detection heuristics
• references/RECOVERY_TRANSFORMS.md - deterministic rewrite transforms
• references/EXAMPLES.md - prompt/response behavior examples
• references/TROUBLESHOOTING.md - ambiguous prompt handling and recovery guidance
• references/AESTHETIC_GUIDE.md - taste / voice / density / imagery / anti-slop rules (output quality)
• references/THEMING_AND_TOKENS.md - color-scheme and opaque-scale gotchas, theme override chain
• references/MOBILE_AND_CONTAINERS.md - container queries vs media queries, drawer pattern, dvh + safe-area
• references/CHEAT_SHEET.md - fast "I want X, use Y" lookup

Trigger Conditions

Activate this skill when the request includes one or more of these signals:

• Build or refactor a page/section using Graffiti classes
• Convert inline-styled markup to class-first markup
• Produce template-like structures (landing, dashboard, blog, settings, chat, forms, navigation)
• Improve markup quality, semantics, responsiveness, or consistency for Graffiti outputs

Do Not Activate For

• Non-UI/backend-only tasks
• Requests to design a brand new CSS framework or token system
• Requests where Graffiti is not the target styling system

Hard Boundaries (Refusal + Redirect Rules)

1. Do not invent class names not present in current Graffiti CSS/docs.
2. Do not invent CSS custom properties (--*) that are not part of Graffiti's documented token/component contracts.
3. Use Graffiti-first composition: exhaust existing classes/tokens before adding custom CSS.
4. Custom CSS is allowed when needed, but apply it systemically: create reusable project-level classes/utilities instead of one-off component-local overrides.
5. Do not hardcode raw color literals (#hex, rgb(), oklch(...)) inline unless explicitly requested.
6. Do not add JS/Svelte state for purely static structure; add state only when interaction or data requirements actually need it.
7. If a requested pattern is not supported by current classes/tokens, return the closest canonical fallback and clearly note the limitation plus an optional reusable extension path.
8. If a matching hosted template baseline exists for the requested intent, use it as the baseline. Do not generate an unrelated structure from scratch unless the user explicitly asks for a fresh build.
9. Do not re-implement built-in Graffiti primitives with bespoke wrappers/CSS/JS. This is a hard fail for critical patterns including dialog/modal, card/card-link, bubble/chat, callout, input-group, form rows/actions.
10. Do not create a duplicate design system (new ad-hoc utility framework, component framework, or token family) when Graffiti primitives already satisfy the request.
11. Do not ship AI-shaped content: generic feature-grid copy, fake testimonials, invented stat numbers, emoji-as-icons, hand-drawn SVG illustrations more complex than a basic shape, "Coming soon" decorative badges, gradient backgrounds on every section. See references/AESTHETIC_GUIDE.md for the full anti-slop list.
12. Do not inline-override hue tokens (--blue, --red, etc.) and expect their opaque scales (--blue-opaque-N) to follow. Use a theme class instead. See references/THEMING_AND_TOKENS.md.
13. Do not use @media queries for component-internal responsiveness. Default to @container queries with container-type: inline-size. See references/MOBILE_AND_CONTAINERS.md.

Graffiti Identity (Non-Negotiable)

Treat these as fixed truths for this skill:

• Graffiti is a class-first drop-in CSS system. Markup should compose existing classes instead of rebuilding primitives with inline CSS.
• Graffiti is the baseline layer for page styling in projects using this skill (elements + layouts + utilities + components + full token system).
• Graffiti is a substrate, not a look. The framework's value comes from re-skinning, not from the default look being everything. Output quality depends on the content + assets + tokens the markup carries — slop in, slop out.
• The source of truth is hosted Graffiti docs/templates plus local package evidence, in this order:

1. https://graffiti-ui.com/base, https://graffiti-ui.com/utilities, https://graffiti-ui.com/elements, https://graffiti-ui.com/ui-blocks requested with Accept: text/markdown, plus topic routes like https://graffiti-ui.com/elements/buttons
2. https://graffiti-ui.com/templates and template pages such as https://graffiti-ui.com/templates/landing, https://graffiti-ui.com/templates/dashboard, https://graffiti-ui.com/templates/blog, https://graffiti-ui.com/templates/settings, https://graffiti-ui.com/templates/ai-chat, https://graffiti-ui.com/templates/docs-portal
3. Installed Graffiti stylesheet/package exports in the target project (actual selectors and variable contracts)
4. Skill recipes in references/* (guidance layer, never higher authority than source files)

• Graffiti variables are contracts, not free-form style knobs. Use documented tokens/overrides only.
• If guidance in skill references conflicts with source files, source files win.

System-First Preflight (Required)

Before writing or editing markup, run this preflight in order:

1. Variables: identify required tokens from https://graffiti-ui.com/base markdown and installed Graffiti CSS contracts.
2. Theme: confirm theme/color intent can be solved with Graffiti tokens/classes first. If theming a non-default surface, consult references/THEMING_AND_TOKENS.md to pick the right override level (theme class vs --primary swap vs component override token).
3. Layout: map top-level structure to existing layout primitives. For mobile-responsive layout primitives, default to @container per references/MOBILE_AND_CONTAINERS.md.
4. Utilities: map text/state/alignment behavior to existing utilities.
5. Components: map each requested UI piece to canonical built-in components.

If any category cannot be mapped, choose a documented fallback and record it before writing final markup.

Aesthetic-First Preflight (Required for content surfaces)

For any surface that includes content (marketing, dashboard with copy, templates, blog, etc.) ALSO run this preflight per references/AESTHETIC_GUIDE.md:

1. Theme: pick a theme class FIRST. Decide whether it lives globally (on <html> / app root) or locally (on a section/feature root). Default-canvas-with-no-theme is a deliberate choice, not a fallback. See references/THEMING_AND_TOKENS.md.
2. Voice: commit to a tone (editorial / technical / product / luxury / brutalist / etc.) and stay in it.
3. Density: declare the per-section content budget (e.g. hero = 1 headline + 1 subhead + 2 CTAs; feature grid = 3–6 items, each ≤30 words). If unsure, default LOW.
4. Imagery: decide what every image slot actually contains. If no real imagery is available, use .box.invisible + gradient-* + monospace label as placeholder. Never invent decorative SVGs.
5. Icons: Graffiti ships no icon set and blesses none. Use whatever icon library the project already includes (check package.json and existing imports first). If the project has no icon library, use the <span class="icon" aria-hidden="true"> placeholder pattern with a single Unicode glyph until a real icon is supplied. Never invent SVG icons more complex than a basic shape (circle / square / arrow / chevron / plus / minus / X / check). Never use emoji as feature icons. Never mix icon sets in one page.

If theme / voice / density / imagery is ambiguous in the user's request and they didn't provide guidance, ASK before generating — do not silently choose generic SaaS defaults.

Component Intent Steering (Required)

Classes are role-bearing primitives, not generic visual wrappers.

Specific-Over-Generic Rule (the anti-generic-container rule)

.box, .stack, .cluster, .split, .surface are fallbacks, not defaults. Reaching for them when a role-specific primitive exists is the single largest source of ugly, generic-looking Graffiti output.

Before composing any container with a neutral wrapper, walk the role menu in this order and stop at the first match:

1. Is this a metric/KPI readout? → .stat-card
2. Is this a feature/value-prop entry? → .feature-card
3. Is this a record-like content unit (article, product, plan, recipe, post preview)? → .card (or .card.featured / .card.linked)
4. Is this a notice / contextual message (info, warning, error, success)? → .callout + semantic variant
5. Is this a chat / message turn? → .chat-thread + .chat-row + .bubble
6. Is this a tool call / activity log entry / function invocation? → .log-card
7. Is this a compact disclosure (FAQ-style)? → <details class="bordered"> + <summary>
8. Is this a modal/confirmation surface? → native <dialog> + .close
9. Is this a form field row / submit row / option label? → .row / .form-actions / .form-option-row
10. Is this an input coupled with one button? → .input-group
11. Is this a multi-line message composer with toolbar? → <form class="composer">
12. Is this a TOC for a long document? → .toc
13. Is this a vertical icon-only nav rail? → .icon-rail
14. Is this a secondary inspector/workbench pane in an app shell? → .workbench-panel inside .layout-rail.with-workbench
15. Is this a selectable pill / filter / suggestion? → .chip (with aria-pressed)
16. Is this a status pill / category label? → .tag (semantic variant first)
17. Is this a pull quote? → <blockquote class="pull-quote">
18. Is this a section eyebrow / overline? → .eyebrow

Only after exhausting the role menu is .box / .stack / .cluster / .split / .surface allowed — and even then, justify why no role primitive fits.

Three-fit validation (apply once a role primitive is selected):

1. Intent fit: component role matches the requested job.
2. Semantic fit: host element semantics match the pattern.
3. Shape fit: content shape (single metric, repeating article, form control row, notice, etc.) matches the primitive.

Hard boundaries: