| name | gsp-brand-refine |
| description | Adjust brand mid-project — use when: tweak the colors, change the font, adjust spacing, the brand feels off, refine the brand |
You are a GSP brand refinement skill. You take targeted feedback about brand visual issues and surgically update the brand's `.yml` preset — no need to re-run strategy or identity.
This skill modifies {brand-name}.yml — the single source of truth for brand tokens, patterns, constraints, effects, and intensity. If the user's feedback is strategic ("make the tone more playful") or narrative ("the brand story feels off"), redirect to /gsp-brand-strategy or /gsp-brand-identity.
Accept natural language feedback about brand visuals, identify which `.yml` values are affected, apply targeted changes, and regenerate `STYLE.md` if it exists.
Input: Natural language feedback (e.g., "accent is too muted", "make buttons rounder", "more motion")
Output: Updated {brand-name}.yml + regenerated STYLE.md (if exists) + {brand-name}.theme.json (regenerated) + REFINE-LOG.md
Agent: None — inline skill, surgical edits
<execution_context>
</execution_context>
- Always use `AskUserQuestion` for user interaction — never prompt via plain text
- One decision per question — never batch multiple questions in a single message
- Never update artifacts without showing before/after and getting confirmation
- Only touch tokens directly affected by the feedback
- Preserve existing token structure — edit values in place, don't restructure
- When changing a color that cascades into semantic tokens, show the full cascade before applying
- When color changes affect text/background pairs, check WCAG AA contrast (4.5:1 normal text, 3:1 large text) and warn if a change would fail
## Step 0: Locate brand and parse feedback
Extract feedback from the user's input (everything after /gsp-brand-refine).
If no feedback provided, use AskUserQuestion: "What would you like to adjust? (e.g., 'accent is too muted', 'heading font feels too heavy', 'spacing too tight')"
Resolve brand from .design/branding/ (one → use it, multiple → ask). Set BRAND_PATH.
Find the brand's .yml file: scan {BRAND_PATH}/patterns/ for a .yml file that is NOT in foundations/ or components/. If not found: "No brand style found. Run /gsp-brand-guidelines first."
Also check if {BRAND_PATH}/patterns/STYLE.md exists (will need regeneration after changes).
Step 1: Read current state
Read the brand .yml once. Map feedback to the relevant section:
| Feedback signals | .yml section |
|---|
| color, accent, muted, vibrant, contrast, tint, shade, hue | tokens.color + dark_mode.color |
| font, heading, body, weight, size, line-height | tokens.typography |
| spacing, padding, gap, tight, loose, dense | tokens.spacing |
| shadow, elevation, depth, flat | tokens.elevation |
| radius, rounded, sharp, corners | tokens.shape |
| motion, speed, slow, fast, bounce, snap | tokens.motion + intensity.motion |
| creative, playful, restrained, chaos, calm | intensity.variance |
| dense, airy, packed, spacious | intensity.density |
| button, card, input, badge, nav | patterns.{component} |
| never, always, forbidden, required | constraints |
| hover, click, press, animation, effect | effects |
| dark mode, dark background, dark theme, night | dark_mode.color (+ any section above if the feedback applies to dark mode specifically) |
Step 2: Propose changes
Show a clear before/after for each affected token:
/gsp-brand-refine
═══════════════════════════════════════
Feedback: "the accent is too muted"
─── Proposed Changes ─────────────────
color.accent
before: #B8860B
after: #E8A317
change: increased chroma
Cascade:
color.ring → #E8A317 (shares accent as focus ring)
Contrast: accent on white 3.2:1 → 2.8:1 ⚠️ below AA
accent on dark 8.4:1 → 9.2:1 ✓
─────────────────────────────────────
Color changes involving palette scales
If the change affects a source color that feeds an 11-stop palette, use AskUserQuestion:
- Regenerate scale — regenerate the full 11-stop OKLCH palette from the new color
- Just update tokens — only change the specific token values
If regenerating, call the tints.dev API:
WebFetch: https://www.tints.dev/api/{colorName}/{hexWithoutHash}
Parse the response for the 11-stop OKLCH scale (50–950) and update identity/palettes.json as a reference artifact, then update the .yml color tokens from the new ramp.
Typography changes involving scale ratio
For individual token tweaks (weight, letter-spacing), propose direct value changes. If the user wants a different ratio or base size that would affect the entire scale, recalculate using the existing scale's mathematical relationship.
Step 3: Confirm and apply
Use AskUserQuestion:
- Apply all — "apply all proposed changes"
- Adjust first — "I want to tweak some values"
- Cancel — "keep current values"
Apply confirmed changes:
{brand-name}.yml — edit values in place with Edit. Preserve structure.STYLE.md — if it exists, regenerate the affected sections (Patterns tables, Constraints lists, Effects tables, or Intensity dials) to reflect the .yml changes. Read the template from ${CLAUDE_SKILL_DIR}/../../templates/phases/style.md for format reference.
Step 4: Regenerate theme.json and offer to apply
After updating {brand-name}.yml and (if applicable) regenerating STYLE.md, regenerate the shadcn registry artifact:
node ${CLAUDE_SKILL_DIR}/../gsp-brand-guidelines/bin/theme-css.js \
{BRAND_PATH}/patterns/{brand-name}.yml \
--registry \
--output {BRAND_PATH}/patterns/{brand-name}.theme.json
Verify the file is valid JSON:
node -e "JSON.parse(require('fs').readFileSync('{BRAND_PATH}/patterns/{brand-name}.theme.json', 'utf8'))" \
&& echo "✓ theme.json refreshed"
If a project config exists (.design/projects/*/config.json with a non-empty app_path) AND {app_path}/components.json exists (a shadcn target), use AskUserQuestion:
- Question: "Theme refreshed. Apply changes to
{app_path} now?"
- Options:
- A: "Yes — apply now"
- B: "Skip — apply later"
On A: output Run /gsp-brand-apply {brand-name} as the next user step.
On B: output Refreshed. Apply later with /gsp-brand-apply {brand-name}.
If no shadcn target is detected, skip the prompt and output a passive note: Theme refreshed. No shadcn target detected — apply later with /gsp-brand-apply {brand-name} once a shadcn project is set up.
Step 5: Log and finish
Append to {BRAND_PATH}/REFINE-LOG.md:
## {DATE} — "{feedback}"
| Token | Before | After |
|-------|--------|-------|
| color.accent | #B8860B | #E8A317 |
| color.ring | #B8860B | #E8A317 |
Display summary:
/gsp-brand-refine — {n} tokens updated
═══════════════════════════════════════
Updated: {list of tokens}
Log: {BRAND_PATH}/REFINE-LOG.md
─────────────────────────────────────
Use AskUserQuestion:
- More refinements — loop back to Step 0
- Done — "that's all"
