brand-system

Hive Brand System

Establish a complete brand identity for the project.

Input: $ARGUMENTS optionally contains brand direction hints (industry, tone, color preferences, existing logo paths).

Before Executing Any Skill

See hive/references/skill-prelude.md — standard skill preamble (persona / config / memory loading).

Gate Check

No gate. brand-system is always runnable — it is the first step in the brand chain.

Process

1. Load ui-designer persona

Read hive/agents/ui-designer.md in full. This is the agent you will spawn. The persona includes Frame0 CLI reference, tool discovery protocol, and output format.

2. Spawn ui-designer for brand foundation

Read and cite hive/references/ui-prompts/brand-system.md as the canonical ui-designer task prompt.

Inject the following placeholder values before passing to the subagent: none.

Spawn a subagent with the full ui-designer persona (hive/agents/ui-designer.md) and the rendered prompt body.

The ui-designer produces:

• .pHive/brand/brand-system.yaml — colors, typography, spacing, personality, plus a top-level concept_directions: array (2-3 short stylistic strings derived from the personality).
• .pHive/brand/brand-guide.html — six-section guide, with the Logo Concepts section rendered as a placeholder (<!-- LOGO_SECTION_PLACEHOLDER -->). No inline-SVG logos at this stage — those are owned by step 3 below.

3. Logo handoff — invoke /logo-exploration (or fall back)

Detect availability of /logo-exploration. It is available iff BOTH:

• skills/logo-exploration/SKILL.md exists on disk, AND
• .mcp.json at the repo root exists and lists an openai-image server entry under mcpServers.

These are the consumer opt-in signals. OPENAI_API_KEY is not checked here — /logo-exploration errors clearly when the key is missing, and that surface message is the right place for the user to learn about it.

Primary path — /logo-exploration available. Invoke the skill:

/logo-exploration --brief .pHive/brand/brand-system.yaml

/logo-exploration reads concept_directions: from the brief (or infers from personality.tone + personality.statement when absent) and writes .pHive/brand/logo-explorations/<timestamp>/contact-sheet.html plus the candidate PNGs. Capture the timestamped directory path it echoes back.

Then patch .pHive/brand/brand-guide.html — replace the <!-- LOGO_SECTION_PLACEHOLDER --> block with a Logo Concepts section that links (not embeds) the latest contact-sheet:

<section class="logos">
  <h2>Logo Concepts</h2>
  <p>Image-backed candidates were generated by <code>/logo-exploration</code>.</p>
  <p><a href="logo-explorations/<TS>/contact-sheet.html">Open the contact sheet →</a></p>
  <p class="next-step">Pick a winner by writing
    <code>.pHive/brand/logo-explorations/&lt;TS&gt;/selected.yaml</code>, then run
    <code>/logo-exploration --refine &lt;TS&gt;</code> for edit variants.</p>
</section>

Use the relative path that resolves from brand-guide.html's on-disk location (.pHive/brand/brand-guide.html and .pHive/brand/logo-explorations/<TS>/ are siblings under .pHive/brand/, so logo-explorations/<TS>/contact-sheet.html is correct — adjust if the consumer moved either artifact).

If /logo-exploration fails (e.g. 403 from gpt-image-2's verified-org requirement, missing OPENAI_API_KEY, MCP server unreachable), propagate the exact error message verbatim, then fall through to the fallback path below — do not crash the brand-system run.

Fallback path — /logo-exploration unavailable (or failed). Re-spawn the ui-designer with the same prompt body plus --inline-svg-logos in $ARGUMENTS. The prompt's fallback branch (see hive/references/ui-prompts/brand-system.md) instructs ui-designer to replace the placeholder with 3-5 inline-SVG concepts and prepend a one-line notice pointing at the dedicated path. The brand guide is still complete and self-contained; only the logo surface differs.

Record which path was taken (primary vs. fallback) for the report in step 4.

4. Report output

After step 3 completes, report:

Brand System Complete

Artifacts:
  Data:         .pHive/brand/brand-system.yaml
  Visual guide: .pHive/brand/brand-guide.html  ← OPEN THIS TO SEE YOUR BRAND
  [if primary path]
  Logo concepts: .pHive/brand/logo-explorations/<TS>/contact-sheet.html
  [if --with-frame0]
  Frame0 file:  .pHive/brand/brand-guide.f0
  PNG export:   .pHive/brand/brand-guide.png  [or: pending manual export]

Colors defined: {count}
  Primary:   {hex} — {name}
  Secondary: {hex} — {name}
  Neutral:   {hex} — {name}
  Surface:   {hex} — {name}

Typography: {heading_font} / {body_font}
Personality: {statement}

Logo concepts:
  [primary path]   Image-backed exploration at .pHive/brand/logo-explorations/<TS>/ — pick a winner by editing selected.yaml.
  [fallback path]  Inline-SVG fallback rendered into brand-guide.html. Install the openai-image MCP and re-run /brand-system for image-backed exploration.

To view:
  open .pHive/brand/brand-guide.html
or
  code .pHive/brand/brand-guide.html

Next: Review the HTML guide and confirm direction. Run /hive:design-system to generate implementation tokens from this brand system.

Key References

• hive/references/html-preview-format.md — HTML preview structure, sections, SVG logo format, styling conventions
• hive/agents/ui-designer.md — ui-designer persona (Frame0 CLI reference, tool discovery)
• hive/references/ui-skill-gates.md — gate spec (brand-system: no gate)
• .pHive/architecture/ui-team-skills-arch.md — brand output format specification
• skills/logo-exploration/SKILL.md — image-backed logo exploration skill invoked in step 3 (primary path)
• hive/references/logo-exploration-artifacts.md — on-disk artifact contract for .pHive/brand/logo-explorations/<TS>/