jubscodes/get-shit-pretty/gsp-brand-refine

<context> 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. </context>

<objective> 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 </objective>

<execution_context> </execution_context>

<rules>

• 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

</rules>

<process>

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:

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:

1. `{brand-name}.yml` — edit values in place with Edit. Preserve structure.
2. `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"

</process>