x-ipe-tool-brand-theme-creator

name	x-ipe-tool-brand-theme-creator
description	Generate design-system.md and component-visualization.html files for custom X-IPE themes based on brand inputs. Extracts colors, typography, and UI component patterns from reference materials. Use when user wants to create a new theme, define brand colors, or build a design system. Triggers on requests like "create theme", "new brand theme", "generate design system", "add custom theme".

X-IPE Brand Theme Creator

Purpose

Transform brand colors, typography preferences, and style guidelines into a complete theme package by:

1. Extracting brand identity from web links, images, or text descriptions
2. Deriving a full color palette from minimal input (one accent color minimum)
3. Extracting basic UI component patterns (buttons, cards, inputs, links, badges, navigation) when visible in source material
4. Generating design-system.md with structured token definitions for AI agents
5. Generating component-visualization.html with visual preview and JSON-LD

---

About

This meta skill produces theme packages consumed by the X-IPE theme system. Each theme lives in its own directory and contains two files: a markdown design system for agent consumption and an HTML visualization for human review.

Key Concepts

• Design System - Structured token definitions (colors, typography, spacing, shadows, component specs) in markdown
• Component Visualization - Self-contained HTML file with CSS variables, visual previews, and JSON-LD structured data
• Color Derivation - Algorithmic expansion of a single accent color into a full palette using Tailwind CSS scales
• Component Extraction - Identification and extraction of UI component patterns (button styles, card layouts, input treatments, link behaviors) from source materials, with sensible defaults as fallback

Scope

operates_on:
  - "Theme packages in x-ipe-docs/themes/theme-{name}/"
  - "Design tokens (colors, typography, spacing, radius, shadows)"
  - "UI component patterns (buttons, cards, inputs, links, badges, navigation)"

does_not_handle:
  - "Application-level CSS or component library code"
  - "Runtime theme switching logic"
  - "Complex component interactions or JavaScript behavior"

---

Important Notes

BLOCKING: Output location is x-ipe-docs/themes/theme-{name}/. The folder name MUST start with theme- prefix (e.g., theme-bilibili, theme-ocean). The ThemesService only discovers folders with this prefix — folders without it will NOT appear in the Toolbox.

CRITICAL: Both design-system.md and component-visualization.html must be generated. Never produce only one file.

CRITICAL: Minimum input is one accent/brand color. All other tokens can be derived. See references/color-derivation.md.

CRITICAL: If the user provides a theme name without the theme- prefix, prepend it automatically (e.g., user says "bilibili-brand" → folder is theme-bilibili-brand).

CRITICAL: Component extraction is best-effort. If the source material has no visible UI components, fall back to derived defaults from references/component-extraction.md. Never block theme generation because components couldn't be extracted.

Note: If Agent does not have skill capability, go to .github/skills/ folder to learn skills. SKILL.md is the entry point.

---

Anti-Patterns

Anti-Pattern	Why Bad	Do Instead
Blocking theme generation on failed component extraction	Theme can still be fully usable with derived defaults	Fall back to defaults, note in output metadata
Generating only one file (design-system.md without visualization, or vice versa)	Consumers expect both files; partial output breaks theme discovery	Always generate both files together
Using RGB/HSL color values in tokens	Inconsistent format breaks downstream parsing	Convert all colors to hex format
Leaving {{PLACEHOLDER}} strings in generated output	Broken rendering and JSON-LD parsing failures	Verify all placeholders replaced before writing files
Skipping user confirmation step	Users may reject extracted colors, causing rework	Always present palette and get confirmation first
Omitting theme- prefix from folder name	ThemesService won't discover the theme	Auto-prepend prefix if missing

---

Input Parameters

<input_init>

1. Read theme_name and accent_color from user request (required).
2. Determine source_type from context: if URL → web_link, if image path → image, if descriptive text → text_description, if hex only → direct.
3. Set extract_components to true unless user explicitly opts out.
4. Apply defaults for all optional parameters not provided by user. </input_init>

input:
  # Primary inputs
  theme_name: "kebab-case name without 'theme-' prefix (e.g., ocean, corporate)"
  accent_color: "hex color value (e.g., #3b82f6) OR derived from source"

  # Input source (one of)
  source_type: "web_link | image | text_description | direct"
  source_value: "URL, image path, or text description"

  # Optional overrides (with defaults)
  primary_color: "derived: darken accent by 40%"
  secondary_color: "derived: desaturate + darken by 20%"
  neutral_color: "derived: very light tint of accent"
  heading_font: "Inter"
  body_font: "system-ui"
  code_font: "JetBrains Mono"
  border_radius_md: "8px"
  extract_components: "true (default) — whether to extract UI component patterns from source"

For detailed extraction procedures per source type, see references/input-sources.md.

---

Definition of Ready

<definition_of_ready>
  <checkpoint required="true">
    <name>Theme Name Provided</name>
    <verification>User specified a theme name or one can be derived from input</verification>
  </checkpoint>
  <checkpoint required="true">
    <name>Color Source Available</name>
    <verification>At least one of: accent color hex, web URL, image, or text description provided</verification>
  </checkpoint>
  <checkpoint required="recommended">
    <name>Reference Theme Accessible</name>
    <verification>theme-default exists at x-ipe-docs/themes/theme-default/ for structural reference</verification>
  </checkpoint>
</definition_of_ready>

---

Execution Flow

Step	Name	Action	Gate
1	Extract Brand Identity	Process input source for colors AND component patterns	Identity extracted
2	Confirm with User	Present extracted palette and component findings for approval	User confirms
3	Derive Full Palette + Components	Apply derivation rules for missing tokens and component defaults	All tokens resolved
4	Generate design-system.md	Fill design system template with token values and component specs	File written
5	Generate visualization	Fill HTML template, replace all placeholders	File written
6	Create Theme Folder	Write both files to x-ipe-docs/themes/theme-{name}/	Files on disk
7	Validate	Verify DoD checkpoints	DoD validated

---

Execution Procedure

<procedure name="brand-theme-creator">
  <execute_dor_checks_before_starting/>
  <schedule_dod_checks_with_sub_agent_before_starting/>

  <step_1>
    <name>Extract Brand Identity</name>
    <action>
      1. Determine input source type (web link, image, text, or direct hex)
      2. Extract colors based on source type:
         IF source_type = web_link: use web_fetch to retrieve page, extract from CSS variables, meta tags, header/nav/CTA colors
         ELSE IF source_type = image: use vision capabilities to identify dominant + accent colors by area coverage
         ELSE IF source_type = text_description: parse brand adjectives, map to color direction and typography per interpretation guide
         ELSE: use provided hex values directly
      3. Map extracted values to theme tokens (primary, secondary, accent, neutral)
      4. IF extract_components == true AND source provides visible UI patterns:
         Extract component patterns per source type (see references/component-extraction.md):
         - Buttons: background, border-radius, padding, font-weight, hover style
         - Cards: border, shadow, padding, border-radius
         - Form inputs: border, border-radius, padding, focus ring style
         - Links: color, hover color, underline behavior, transition
         - Badges: background, padding, border-radius, font-size
         - Navigation: height, background, padding, item spacing
      5. Record which components were extracted vs which need defaults
    </action>
    <constraints>
      - BLOCKING: For web links, always use web_fetch — never guess colors
      - CRITICAL: Extract hex values only; no RGB or HSL in theme tokens
      - Component extraction is best-effort; missing components use defaults from Step 3
    </constraints>
    <output>Extracted color values and component patterns mapped to theme token roles</output>
  </step_1>

  <step_2>
    Confirm with User
    
      1. Present extracted/interpreted colors to user
      2. IF components were extracted: present component findings summary (e.g., "Found: rounded buttons with 12px radius, elevated cards with large shadow")
      3. Ask for theme name if not already provided
      4. Validate theme name: IF name does not start with "theme-", prepend "theme-" prefix
      5. Offer customization options (typography, border radius, component overrides)
    
    
      - BLOCKING: Do not proceed to generation without user confirmation
      - BLOCKING: Final folder name MUST start with "theme-" prefix. Auto-prepend if missing.
    
    Confirmed color palette, component patterns, and configuration
  

  
    Derive Full Palette + Components
    
      1. Apply color derivation rules for any unspecified tokens
      2. Select appropriate Tailwind neutral scale (slate, gray, zinc, stone, etc.)
      3. Resolve semantic colors (success=#22c55e, warning=#f59e0b, error=#ef4444, info=#3b82f6)
      4. Compute accent variants (light bg at 10% opacity, focus ring at 15% opacity)
      5. Verify contrast ratios: primary/secondary on white >= 4.5:1, accent on white >= 3:1
      6. For each component type NOT extracted in Step 1, apply defaults from references/component-extraction.md:
         - Buttons: use accent color, border-radius from radius_md, standard padding
         - Cards: use neutral scale borders, standard shadow, 24px padding
         - Inputs: use neutral scale borders, radius_md, standard padding
         - Links: use accent color, darken on hover
         - Badges: use accent light bg, small radius, compact padding
         - Navigation: derive from primary color and heading font
      7. Merge extracted components with derived defaults (extracted values take precedence)
    
    Complete token set with all colors, typography, spacing, radius, shadows, and component specs
  

  
    Generate design-system.md
    
      1. Load template from templates/design-system-template.md
      2. Fill all token sections: colors, typography, spacing, radius, shadows
      3. Fill component specs section with extracted or derived values for:
         buttons, cards, form inputs, links, badges, navigation
      4. Add CSS variables block including component-level variables
    
    Completed design-system.md content
  

  
    Generate component-visualization.html
    
      1. Load template from templates/component-visualization-template.html
      2. Replace all {{PLACEHOLDERS}} with resolved token values
      3. Include JSON-LD structured data block with all tokens (including component specs)
      4. Verify no unreplaced placeholder strings remain
    
    
      - BLOCKING: All placeholders must be replaced; see references/template-placeholders.md
      - CRITICAL: JSON-LD block must be present for AI parsing
    
    Completed component-visualization.html content
  

  
    Create Theme Folder
    
      1. Verify theme name starts with "theme-" prefix. If not, prepend it.
      2. Create directory x-ipe-docs/themes/theme-{name}/
      3. Write design-system.md
      4. Write component-visualization.html
    
    
      - BLOCKING: Folder name MUST match pattern "theme-{name}". ThemesService rejects folders without this prefix.
    
    Theme directory with both files on disk
  

  
    Validate
    
      1. Confirm theme directory exists with both files
      2. Verify no {{PLACEHOLDER}} strings remain in generated files
      3. Verify JSON-LD block is present in HTML file
      4. Check that theme appears in /api/themes response
      5. Test that 4 color swatches display correctly
      6. Verify component specs section has at least buttons, cards, and inputs
    
    
      - Both files exist at correct path
      - No unreplaced placeholders
      - Theme discoverable by API
      - Component specs present with at least 3 component types
    
    Validated theme package
  

---

Output Result

task_completion_output:
  category: standalone
  status: completed | blocked
  next_task_based_skill: null
  require_human_review: "yes"
  task_output_links:
    - "x-ipe-docs/themes/theme-{name}/design-system.md"
    - "x-ipe-docs/themes/theme-{name}/component-visualization.html"
  theme_name: "theme-{name}"
  source_type: "web_link | image | text_description | direct"
  colors_confirmed: "true | false"
  components_extracted: "list of component types extracted from source"
  components_derived: "list of component types using defaults"

---

Definition of Done

CRITICAL: Use a sub-agent to validate DoD checkpoints independently.

<definition_of_done>
  <checkpoint required="true">
    <name>Design System Created</name>
    <verification>design-system.md exists at x-ipe-docs/themes/theme-{name}/ with all token sections populated</verification>
  </checkpoint>
  <checkpoint required="true">
    <name>Visualization Created</name>
    <verification>component-visualization.html exists with no unreplaced {{PLACEHOLDER}} strings</verification>
  </checkpoint>
  <checkpoint required="true">
    <name>JSON-LD Present</name>
    <verification>component-visualization.html contains JSON-LD structured data block</verification>
  </checkpoint>
  <checkpoint required="true">
    <name>Colors in Hex</name>
    <verification>All color tokens use hex format (not RGB or HSL)</verification>
  
  
    Contrast Verified
    Primary/secondary on white >= 4.5:1 ratio; accent on white >= 3:1
  
  
    User Confirmed Palette
    Extracted/derived colors were presented to and confirmed by user before generation
  
  
    Component Specs Present
    Component Specs section includes at least buttons, cards, and form inputs with either extracted or default values
  

---

Templates

File	Purpose	When to Use
templates/design-system-template.md	Markdown design system structure with token placeholders	Generating design-system.md
templates/component-visualization-template.html	HTML preview with CSS variables and JSON-LD	Generating component-visualization.html

---

Examples

See references/examples.md for concrete theme generation examples covering web link, image, text, and minimal input scenarios, including component extraction.

References

• references/input-sources.md - Detailed extraction procedures per source type
• references/color-derivation.md - Color derivation rules, defaults, and Tailwind scale mapping
• references/color-scales.md - Full Tailwind CSS color scale values
• references/template-placeholders.md - Complete placeholder table and output file structure
• references/component-extraction.md - Component extraction patterns, defaults, and override logic