# Kalebtec Icon Design

Self-contained instructions for turning an icon brief into numbered discovery
and refinement rounds, then a validated production package. Use the visual
builder at https://icons.kalebtec.com/ or follow this file in any capable agent
UI or terminal UI.

Version: 1.5.1
Updated: 2026-07-14
Repository: https://github.com/kalebteccom/claude-icon-design
License: MIT for plugin and website code. Generated assets use the license
selected for the project. The Kalebtec name, logo, and mark are the exclusive
property of Kalebtec, copyright © 2026 Kalebtec, all rights reserved, and are
not licensed under MIT.

## Fastest route

Choose the first available route:

1. Codex: invoke `$icon-design`.
2. Claude Code: invoke `/icon-design:icon-design`.
3. Any other agent: open https://icons.kalebtec.com/, finish the three brief
   steps, choose “Another chatbot,” and paste the exported prompt into the chat.
4. A repository-aware agent can follow this file directly.

Recommended opening requests:

```text
Use $icon-design to open the guided brief builder for a new icon project.
```

```text
/icon-design:icon-design
Open the guided brief builder for a new icon project.
```

If the user supplied a complete brief, begin discovery. If the user pasted a
builder export, treat it as the agreed brief and do not repeat its questions.

## Install

Codex:

```sh
codex plugin marketplace add kalebteccom/claude-icon-design
codex plugin add icon-design@kalebtec-icon-design
```

Start a new conversation after installation.

Claude Code:

```sh
claude plugin marketplace add kalebteccom/claude-icon-design
claude plugin install icon-design@kalebtec-icon-design
```

Restart Claude Code or run `/reload-plugins` after installation.

## Resolve bundled files

`<skill-directory>` below is the absolute directory containing `SKILL.md`.

- Codex: use the installed path supplied with the skill.
- Claude Code: `${CLAUDE_PLUGIN_ROOT}/skills/icon-design`.
- Repository checkout: `plugins/icon-design/skills/icon-design`.

Read these bundled files when they apply:

- `references/three-stage-workflow.md` for new discovery and refinement work.
- `references/round-manifest.md` before writing `concepts.json`.
- `references/design-method.md` before drawing, refining, or auditing.
- `references/delivery-contract.md` before final delivery.
- `assets/concept-sheet.example.json` for discovery.
- `assets/refinement-sheet.example.json` for refinement.
- `assets/shortlist-sheet.example.json` for multi-parent refinement.
- `assets/design-spec.example.json` for the final suite.

Never write project work into an installed skill directory. It may be an
installation cache.

## Optional guided brief

Web:

```text
https://icons.kalebtec.com/
```

Bundled local file:

```sh
python3 "<skill-directory>/scripts/launch_brief_builder.py"
```

Print its file URL without opening it:

```sh
python3 "<skill-directory>/scripts/launch_brief_builder.py" --print-url
```

The builder has three preparation steps:

1. Purpose: project, icon class, job, audience, metaphor territories, and
   things to avoid.
2. References: up to three original visual-language specimens.
3. Character: a Guided preset or six Custom 1–5 axes with a 64-cell reference
   matrix.

It always asks for 20 discovery ideas and the complete final package. Optional
size, background, palette, and handoff constraints stay under “Customize
delivery.” It can copy a prompt, save text, save JSON, and import JSON. No brief
is uploaded.

## Production rule

Run new work in exactly three production stages:

1. Discovery.
2. Refinement.
3. Final.

The guided brief is preparation, not a fourth stage. Stop after every discovery
or refinement handoff. Never choose a winner for the user.

## Rendering setup

Prepare the renderer before the first discovery sheet:

```sh
python3 -m pip install -r "<skill-directory>/scripts/requirements.txt"
```

Or run it in an isolated environment:

```sh
uv run --with cairosvg --with pillow python \
  "<skill-directory>/scripts/render_concept_sheet.py" \
  path/to/concepts.json \
  --output path/to/review.png
```

On Apple Silicon with Homebrew, if CairoSVG cannot find Cairo, prefix the
command with `DYLD_FALLBACK_LIBRARY_PATH=/opt/homebrew/lib`.

## Working project

```text
icon-project/
  brief.json
  discovery/
    d1/
      concepts.json
      D1-01.svg ... D1-20.svg
      discovery-d1.png
      discovery-d1.html
  refinement/
    r1/
      concepts.json
      R1-01.svg ... R1-08.svg
      refinement-r1.png
      refinement-r1.html
  archive/
    rejected-round/concepts.json
    rejected-round/*.svg
  final/
    source/design.json
    source/mark.svg
    brand-suite/
    <slug>-brand-suite.zip
```

Use `D<round>-<two-digit number>` for discovery and
`R<round>-<two-digit number>` for refinement. Never recycle an ID. Archive
rejected source SVGs and manifests; generated review pages can be reproduced.

## Stage 1: discovery

Generate 20 genuinely different representations by default. Normally use five
useful territories with four structurally different constructions in each.
Change metaphor, silhouette, construction, negative space, and visual rhythm.
Styling changes alone do not count as separate concepts.

Create one square monochrome `currentColor` SVG per concept. Use schema
`kalebtec.icon-round.v2`:

```json
{
  "schema": "kalebtec.icon-round.v2",
  "project": "Northstar",
  "wordmark": "Northstar",
  "stage": "discovery",
  "round": 1,
  "mode": "territory",
  "count": 20,
  "subtitle": "Five territories, four distinct constructions in each.",
  "references": [],
  "retired": [],
  "review": { "selection_max": 5 },
  "concepts": [
    {
      "id": "D1-01",
      "title": "Signal Window",
      "file": "D1-01.svg",
      "territory": "Signal made legible",
      "move": "A narrow opening turns a noisy field into one clear bearing.",
      "watch": "The opening must survive at 16 px."
    }
  ]
}
```

Use `mode: "open"` only when grouping would create false certainty. Every
concept still needs a territory label.

Render the standard matching PNG and standalone HTML review sheets:

```sh
python3 "<skill-directory>/scripts/render_concept_sheet.py" \
  path/to/discovery/d1/concepts.json \
  --output path/to/discovery/d1/discovery-d1.png
```

The command writes `discovery-d1.png` and `discovery-d1.html`. The HTML embeds
all SVGs and styles, runs without a server, supports ordered ID selection, and
copies the next request. The PNG and HTML must show the same groups, IDs,
lineage, and contexts.

Open and inspect both. Confirm large, lockup, 16/24/32 px, reverse, and app-tile
views. Deliver both with a compact territory map. Stop after the sheet.

Useful user continuations:

```text
Refine D1-07.
Refine the shortlist D1-07, D1-12, and D1-18.
Continue discovery from D1-07 and D1-12, but make the next round quieter.
Change the brief: avoid enclosed badges and explore an open silhouette.
```

Continued discovery uses `D2-*`, `D3-*`, and so on.

## Stage 2: refinement

Choose a mode that matches the request:

- `shortlist`: develop several promising parents in one grouped round.
- `controlled`: hold the parent steady and change one deliberate variable per
  candidate.
- `exploratory`: allow larger structural moves while preserving the idea.
- `optical`: keep topology fixed and tune weight, spacing, alignment, and
  native-size behavior.

One parent normally gets eight candidates. For several parents, use enough
candidates to compare each fairly and group them by parent.

References make the decision honest:

- `parent`: source geometry being developed; it stays unchanged and selectable
  in the reference bar.
- `control`: unchanged non-parent candidate kept in the race.
- `benchmark`: unchanged reviewed high-water mark.

Every refinement concept names a reference whose role is `parent`. Keep all
references visible and selectable. A parent, control, benchmark, or new
candidate can win. When several selected sources are being developed, give each
role `parent` and use `assets/shortlist-sheet.example.json`.

```json
{
  "schema": "kalebtec.icon-round.v2",
  "project": "Northstar",
  "wordmark": "Northstar",
  "stage": "refinement",
  "round": 1,
  "mode": "controlled",
  "count": 8,
  "subtitle": "Eight focused moves against one unchanged parent.",
  "references": [
    {
      "id": "D1-07",
      "title": "Selected parent",
      "file": "../../discovery/d1/D1-07.svg",
      "role": "parent",
      "note": "Keep unchanged, selectable, and grouped with its variants."
    }
  ],
  "retired": [],
  "review": { "selection_max": 3 },
  "concepts": [
    {
      "id": "R1-01",
      "title": "Wider counter",
      "file": "R1-01.svg",
      "parent": "D1-07",
      "territory": "Counter proportion",
      "move": "Opens the counter without changing the silhouette.",
      "watch": "Check whether the junction feels too light.",
      "risk": "May lose the parent's compactness."
    }
  ]
}
```

Render with the same command and inspect both outputs. Explain only the
meaningful differences, then stop. The user can finalize a candidate or parent,
refine one or more further, or return to discovery.

Continued refinement uses `R2-*`. If `R4-01` through `R4-12` were abandoned,
put them in `retired` and begin the replacement at `R4-13`. IDs within one
manifest must remain consecutive. If current numbering begins above `01`, every
earlier ID in that stage and round must be listed in `retired`. Current concept,
reference, and retired IDs cannot overlap.

A reference filename must begin with its ID, such as `D1-07.svg` or
`D1-07-signal-window.svg`. This keeps the visible source geometry tied to the
recorded lineage. Set `review.selection_max` to at least 3 when the reviewer may
carry several IDs into another round; finalization still requires one ID.

Only include a rating when a person supplied it. Ratings belong on references,
which represent already reviewed work; never pre-rate a new concept:

```json
{
  "value": 8.5,
  "out_of": 10,
  "attributed_to": "Rowin"
}
```

Never invent approval, scores, or testimonials.

## Stage 3: final

Begin only from an explicit user choice, or from an approved SVG supplied for
cleanup and export. Copy the selected source geometry into
`final/source/mark.svg`; change it only for documented optical correction.

The canonical master must be square and monochrome with visible paint expressed
as `currentColor`. Keep color, depth, and material in derived contexts.

Prepare:

```text
final/source/
  design.json
  mark.svg
```

Minimum `design.json`:

```json
{
  "name": "Product name",
  "slug": "product-name",
  "aria_label": "Product name",
  "description": "A compact mark for Product name.",
  "story": "The visual idea and why its geometry supports it.",
  "source_svg": "mark.svg",
  "palette": {
    "ink": "#202124",
    "paper": "#F8F9FA",
    "paper_bright": "#FFFFFF",
    "paper_shadow": "#DADCE0",
    "background_top": "#202124",
    "background_bottom": "#303134",
    "accent": "#4C8BF5"
  },
  "geometry": {
    "tile_radius_ratio": 0.22,
    "favicon_mark_scale": 0.78,
    "app_mark_scale": 0.78,
    "avatar_mark_scale": 0.86,
    "preview_margin_ratio": 0.098,
    "preview_radius_ratio": 0.181
  },
  "material": "glass",
  "license": {
    "mode": "all-rights-reserved",
    "holder": "Product name",
    "year": 2026
  }
}
```

Render and validate:

```sh
python3 "<skill-directory>/scripts/render_suite.py" \
  --source path/to/final/source \
  --output path/to/final/brand-suite

python3 "<skill-directory>/scripts/validate_suite.py" \
  path/to/final/brand-suite \
  --zip path/to/final/<slug>-brand-suite.zip
```

Install dependencies outside the deliverable if needed:

```sh
python3 -m pip install -r "<skill-directory>/scripts/requirements.txt"
```

Or use an isolated run:

```sh
uv run --with cairosvg --with pillow python \
  "<skill-directory>/scripts/render_suite.py" \
  --source path/to/final/source \
  --output path/to/final/brand-suite
```

On Apple Silicon with Homebrew, if CairoSVG cannot find Cairo, prefix the
command with:

```sh
DYLD_FALLBACK_LIBRARY_PATH=/opt/homebrew/lib
```

## Standard final package

The complete package is the default. It includes:

- canonical `<slug>-mark.svg` using `currentColor`;
- fixed black and white SVGs;
- rounded-tile favicon SVG;
- multi-size `favicon.ico` and 16/32/48 px PNGs;
- 180 px Apple touch icon;
- opaque 1024 px app icon;
- transparent rounded 1024 px app preview;
- opaque circle-crop-safe 512 px avatar;
- flat Apple Icon Composer background and mark layers;
- app-icon and favicon comparison sheets;
- `design.json`, `render.py`, `requirements.txt`, `README.md`, and `LICENSE`;
- a neighboring reproducible zip matching the uncompressed suite.

Keep briefs, discovery, refinement, prompts, chat logs, local paths, temporary
environments, and screenshots outside the production zip.

## Drawing rules

Translate the brief through:

```text
brand or task -> useful metaphor -> basic shapes -> distinctive move
```

- Research category conventions and obvious competitors when web access is
  available. Avoid collisions; never trace or claim trademark clearance.
- Use a square grid, deliberate safe area, repeated dimensions, few anchor
  points, and coherent corner and angle systems.
- Judge the outside silhouette and largest counters before details.
- Check square, rounded-square, circle, light, dark, muted, selected, lockup,
  and app-tile contexts as relevant.
- Inspect 16, 20, 24, 32, and 48 px at native size. Protect counters and gaps.
  Draw a dedicated small-size optical variant when scaling fails.
- Use at least 3:1 contrast for meaningful graphical objects. Do not use color
  as the only state signal.
- Pair ambiguous workflow icons with text. Give meaningful UI icons accessible
  names and hide decorative icons from accessibility APIs.

The canonical SVG must have no embedded bitmap, external reference, script,
text object, decorative filter, or unnecessary editor metadata.

## Visual and automated validation

Rendering and looking are mandatory. Source inspection is not a visual check.

Confirm:

- metaphor and silhouette survive native sizes;
- counters stay open;
- the mark is optically centered in square and circular crops;
- tile radius and mark scale feel related;
- light mark contrast is at least 3:1 against both background endpoints;
- app master is opaque;
- rounded previews have transparent corners;
- Composer mark layer is flat and transparent outside the mark;
- fixed SVGs contain no `currentColor`;
- canonical SVG contains no bitmap, script, or external reference;
- the zip exactly matches the uncompressed suite.

Automated validation checks structure and formats. It does not decide whether a
mark is good.

## Handoff

Report:

- chosen concept ID and lineage;
- final zip and uncompressed suite paths;
- smallest verified size;
- optical corrections made;
- backgrounds and contexts checked;
- remaining limits.

Keep notes factual. Do not invent tests, approval, trademark clearance, or
scores. Do not add tool attribution to generated brand assets or their README.

## Repository development

Run the site:

```sh
npm install
npm run dev
```

Run web tests, build, and sync the plugin builder:

```sh
npm run check
```

Run renderer and workflow tests:

```sh
uv run --with cairosvg --with pillow python -m unittest discover -s tests -v
```

Validate Claude Code packaging:

```sh
claude plugin validate plugins/icon-design --strict
claude plugin validate . --strict
```

Validate the Codex plugin:

```sh
uv run --with pyyaml python \
  "${CODEX_HOME:-$HOME/.codex}/skills/.system/plugin-creator/scripts/validate_plugin.py" \
  plugins/icon-design
```

Deploy the linked Netlify site:

```sh
netlify deploy --build --prod
```

## Authoritative links

- Builder: https://icons.kalebtec.com/
- Repository: https://github.com/kalebteccom/claude-icon-design
- Agent guide: https://icons.kalebtec.com/llms.txt
- Kalebtec brand-asset notice:
  https://github.com/kalebteccom/claude-icon-design/blob/main/BRAND-ASSETS.md
- Material Design 3 icon guidance:
  https://m3.material.io/styles/icons/designing-icons
- Adobe effective icons, Part 1:
  https://adobe.design/ideas/how-to-design-effective-icons-part-1
- Adobe effective icons, Part 2:
  https://adobe.design/ideas/how-to-design-effective-icons-part-2
- Icons8 pixel-perfect guide:
  https://icons8.com/blog/articles/make-pixel-perfect-icons/
- Figma logo design guide:
  https://www.figma.com/resource-library/how-to-design-a-logo/
- Supercharged Studio logo design math:
  https://www.supercharged.studio/blog/mathematical-logo-design