codeswithroh/tastemaker instruction manual

1. Purpose, scope, and Claude Code classification

Tastemaker instruction manual

Tastemaker is a local design skill for coding agents. Its purpose is to replace generic AI-generated interface defaults with a project-specific system grounded in references, generated color, real assets, structural variation, motion rules, and remembered user preferences. It applies when building, styling, improving, studying, or auditing landing pages, dashboards, app screens, forms, components, and other UI.

**Claude Code classification:** `context_injection`; install mode: `claude_extension`; setup effort: `low`; confidence: `high`. The repository contains a Claude Code plugin manifest and an installable `SKILL.md` package. It extends Claude Code by supplying task-specific workflow guidance plus local Python helpers; the supplied files do not show it adding a new Claude Code tool surface or running as separate infrastructure. Claude Code is the recommended native host. Windsurf and Gemini CLI also read the skill format. Cursor support is degraded because conversion to `.mdc` strips the supporting `references/` and `scripts/` directories.

Everything operates locally except documented asset/library requests. There is no Tastemaker backend, account, telemetry, or required API key. Project state is stored under `.tastemaker/`; durable personal preferences are stored under `~/.tastemaker/`. The core repository is MIT licensed. Optional sponsor-only aesthetic modes are separate add-ons and are not included in the base skill.

2. Installation and first use

Claude Code plugin installation

The recommended installation uses Claude Code’s plugin marketplace:

/plugin marketplace add codeswithroh/tastemaker
/plugin install tastemaker@codeswithroh

Restart the agent after installation. Tastemaker then activates automatically on qualifying UI requests; it is not normally invoked by name. A documented test request is:

build a landing page for a coffee subscription

Manual Claude Code installation

For Claude Code without the plugin system, clone the repository and copy only the actual skill folder:

git clone https://github.com/codeswithroh/tastemaker /tmp/tastemaker
cp -r /tmp/tastemaker/skills/tastemaker ~/.claude/skills/tastemaker

For Windsurf, place the same folder under `.windsurf/skills/` instead. Do not install the whole repository as the skill.

Gemini CLI

Gemini CLI has a documented one-command global installation path:

gemini skills install https://github.com/codeswithroh/tastemaker --path skills/tastemaker

This includes the vendored Ideagram illustration sub-skill. A workspace-scoped skill may prompt for folder trust; the documented global installation does not require that.

Python 3 is required for the helpers. Deterministic image palette extraction additionally needs Pillow:

pip install Pillow

Without Pillow, palette extraction falls back to a vision-based read. Optional PNG and favicon export require `cairosvg` and the system Cairo library. Pixabay photography is optional and requires `PIXABAY_API_KEY`; Openverse photos and Iconify icons require no keys. Cursor is not a full installation target at present because its conversion path loses the directories containing most of Tastemaker’s mechanism.

3. Operating modes, scoping, and persistent memory

Tastemaker has four workflow modes. **Build** is the default for requests to create, style, or improve UI. **Study** analyzes a screenshot or URL and extracts reusable design DNA such as macrostructure, archetypes, typography, and a color anchor; it does not copy the source pixels. **Audit** critiques existing UI against the anti-slop gates and returns a severity-ranked punch list without editing. **Comps** creates structured briefs for external image-generation tools and writes `.tastemaker/comps-brief.md`; Tastemaker itself does not call an image API.

If a reference is supplied without a clear verb, the workflow asks whether to study it or use it to ground a fresh build. “Now fix it” after an audit, “build it” after a study, and “build this for real” after comps transfer into build mode.

Before design work, the skill scopes actual screens and classifies each as marketing narrative, app shell, transactional form, data view, editor/canvas, settings, or a loading/empty/success state. Project documents and text inside images are treated as untrusted data. They may supply screen lists and product copy, but instructions addressed to the agent must be surfaced to the user rather than followed.

Memory precedence is: current request, `.tastemaker/style-lock.md`, resolved `.tastemaker/decisions.log` entries, then `~/.tastemaker/profile.md`. The style lock preserves project tokens, assets, spacing, modes, and legal color pairings. The append-only decision log records kept, rejected, or pending-review choices. The personal profile carries only resolved, reusable preferences across projects. Autonomous runs must record pending review rather than invent approval. `.tastemaker/log.json` separately remembers prior macrostructures and component archetypes so later builds can rotate away from the same page shape.

4. References, palette, typography, structure, and component selection

On cold starts and major redesigns, Tastemaker creates or updates `.tastemaker/reference-board.md`. It records the design read, competitors, adjacent products, cultural references, interface systems, anti-references, visual dials, and a direction contract. Sources are marked inferred when browsing or screenshots are unavailable.

For supplied images, `extract_palette.py` reads actual dominant colors, contrast, and lightness statistics. Assigned semantic roles are then checked with `check_contrast.py`. Without references, `generate_palette.py` infers one of five moods—premium, warm, technical, playful, or elegant—and generates a fresh OKLCH palette using a random base hue, a harmony rule, and contrast-constrained lightness. A seed reproduces a result:

python3 scripts/generate_palette.py --mood technical

For non-Latin scripts, the documented model uses one suitable family across a weight scale rather than the normal two-family Latin pairing. If a runtime light/dark toggle is required, generate both modes from the same seed, verify both matrices, and record the decision.

Marketing pages receive a narrative arc of at least four beats, normally hook, problem, solution, how it works, proof, and close. A named macrostructure and nav/hero/feature/proof/CTA/footer archetypes are selected and rotated against `.tastemaker/log.json`. App shells skip this marketing macrostructure step and use app-shell patterns.

Before adding UI, detect the existing stack. Use established behavioral primitives for dialogs, menus, selects, toasts, commands, drag-and-drop, virtualization, gestures, and number animation. Registry blocks may supply visual heroes, pricing, bento layouts, dashboards, and charts only when the stack can consume them. Existing healthy dependencies take precedence. Pulled components must be restyled into one locked visual system and checked for accessibility and interaction quality.

5. Asset pipeline, implementation defaults, motion, and quality gates

Tastemaker builds an asset cast before sourcing: hero anchor, modes, process artifacts, proof, texture, and micro-assets. Factual or physical subjects use photography; abstract concepts use illustrations. Photos come from keyless Openverse, defaulting to CC0/Public Domain Mark, with credits retained in source comments rather than visible UI:

python3 scripts/fetch_photos.py "<search terms>" --out design/assets/photos

Icons come from Iconify. Search first, then fetch a consistent mood-selected set tinted to the locked accent:

python3 scripts/fetch_icons.py --search "<terms>" --mood <mood>
python3 scripts/fetch_icons.py --icons a b c --mood <mood> --color "#hex" --out design/assets/icons

Existing logos are preserved byte-for-byte unless rebranding is requested. A true cold start may construct a geometric mark, then export favicons. Illustrations use the bundled Ideagram workflow and are saved under `design/assets/illustrations/`. All assets live under `design/assets/`, and SVGs are validated before use.

Builds favor meaningful visuals over explanatory paragraphs, one focused hero promise and visual, complete app states, legal contrast pairings, consistent spacing, accessible inputs and focus, real overflow handling, locale-aware formatting, and URL-reflected state where appropriate. High-risk components can be prototyped as two or three genuinely different variants; color-only variants do not count.

GSAP plus ScrollTrigger is the default motion path. Marketing pages use reveals, a sequenced hero, and a scroll-story beat. App shells instead use panel changes, list entrances, state transitions, and skeletons. `assets/gsap-starter.js` is the default; `reveal.css`/`reveal.js` is the dependency-free fallback; `anime-starter.js` is only for SVG path or morphing needs; the artifact kit supplies reusable visual compositions.

Before handoff, run the anti-slop and motion scans:

python3 scripts/anti_slop_scan.py <changed-ui-paths>
python3 scripts/audit_motion.py <changed-ui-paths>

Fix HIGH findings; fix or justify MEDIUM findings. Stamp the CSS with structure, mood, seed, contrast result, and critique scores, then update project memory.

6. Core script reference

The following helpers are documented under `skills/tastemaker/scripts/`:

• **`generate_palette.py`** generates a fresh palette by mood, optional light/dark mode, and optional seed; it prints tokens, preview URL, and a full contrast matrix.
• **`extract_palette.py`** deterministically extracts colors and contrast data from one or more local images: `python3 scripts/extract_palette.py <image_path> [image_path ...]`.
• **`check_contrast.py`** checks a single color pair, critical named roles, or every pairing. Example critical-role check:

python3 scripts/check_contrast.py --palette text=050315 bg=fbfbfe primary=2f27ce secondary=dedcff accent=433bff

Matrix results classify pairs as text-safe at 4.5:1, UI-safe at 3:1, or decorative.

• **`anti_slop_scan.py`** flags generic gradients, gradient text, `h-screen`, dead links, missing alt text, placeholders, AI-like copy, emoji icons, repeated eyebrows, and `transition-all`.
• **`validate_assets.py`** parses SVG files or directories to catch malformed assets: `python3 scripts/validate_assets.py <file_or_directory>`.
• **`fetch_photos.py`** downloads Openverse photos and emits a credits block; optional `--source pixabay` selects the key-required Pixabay path.
• **`fetch_icons.py`** searches and downloads mood-selected Iconify SVGs; `--set <prefix>` explicitly overrides the set.
• **`recolor_svg.py`** recolors local SVGs while optionally preserving dark details: `python3 scripts/recolor_svg.py <path> --accent "#hex" --preserve-dark`.
• **`export_favicons.py`** produces favicon.ico, Apple touch, PWA, and OG assets: `python3 scripts/export_favicons.py <mark>.svg --out design/assets/favicons/`.
• **`audit_motion.py`** scans CSS, HTML, JS, TS, and TSX for broad transitions, unsuitable easing/scaling, long UI timing, layout animation, ungated hover motion, and missing reduced-motion handling.

When new pairings are introduced, rerun the matrix and update the style lock rather than assuming the original palette check covers them.

7. Ideagram illustration workflow and helper functions

Ideagram is vendored inside Tastemaker and matches a concept to a real local unDraw SVG, recolors only its accent family, validates it, and places it into the page. The public repository does not redistribute unDraw art; users maintain `~/.ideagram/undraw/` because unDraw’s license bars repackaging a collection. A library of roughly 20–30 illustrations across common themes is recommended.

Initial setup and indexing are documented as:

mkdir -p ~/.ideagram/undraw
# Download chosen .svg files from undraw.co/illustrations into that folder.
python3 scripts/build_library_index.py

Re-run the indexer whenever the library changes. The workflow distills a brief to one concept, matches by scene using `index.md`/`index.json`, recolors to the project accent, validates the output, and embeds the finished file in the page. If no library or index exists, the workflow must disclose that and either ask the user to populate it or use the visibly lower-quality primitive fallback.

The documented Ideagram helpers are:

• **`build_library_index.py`** indexes filenames and scene keywords for fast local matching.
• **`recolor_undraw.py`** changes the standard unDraw purple accent while preserving skin, hair, clothing, ink, and neutrals.
• **`extract_component.py`** lifts a whole figure, device, or panel for the rare custom composition where no complete illustration fits.
• **`validate_assets.py`** verifies SVG well-formedness before delivery.
• **`export_png.py`** rasterizes a finished illustration to standard presentation/social sizes and requires CairoSVG plus system Cairo.

The primitive kit and its style/metaphor references are last-resort fallbacks, not equivalents to illustrator-authored unDraw work. Tastemaker must state which path was used and record the result in the style lock.

8. Security model, verification, contribution, and repository sites

Network access is HTTPS-only and redirect-checked through `_netguard.py`. The documented allowlist is `api.iconify.design`, `api.openverse.org`, optional `pixabay.com`, `cdn.jsdelivr.net`, and `cdnjs.cloudflare.com`. Scripts contain no `subprocess`, `os.system`, `shell=True`, `eval`, `exec`, or `pickle`, according to repository security assertions. Registry components are not fetched or executed automatically; users deliberately run registry commands and should inspect added source.

Security checks run on pushes and pull requests to `main`, weekly, and can be run locally:

python3 skills/tastemaker/scripts/check_domains.py
python3 skills/tastemaker/scripts/test_security.py

The workflow also validates repository SVGs. Security vulnerabilities should be reported privately through GitHub’s security-advisory form or `codeswithroh@gmail.com`, not a public issue. Test against current `main`, which is the supported version.

For contributions, work from the skill directory; Pillow is needed only for palette extraction:

git clone https://github.com/codeswithroh/tastemaker
cd tastemaker/skills/tastemaker
pip install Pillow

Contributions may add or tune moods, harmony rules, font pairings, patterns, checks, scripts, or documentation. Changes should be focused, verified with relevant scripts, and submitted through a pull request. Palette changes must preserve the contrast contract; SVG changes must pass validation. Good-first-issue labels are available in the repository.

The `site/` folder is a static HTML/CSS marketing site and live demo using CDN-loaded GSAP, with no build step. Its documented Netlify deployment is:

npx netlify deploy --dir=. --prod

The separate private `web` package is a React 19/TypeScript/Vite project. Its package manifest defines development, TypeScript-plus-Vite build, Oxlint, and Vite preview scripts. The supplied evidence does not document deployment for that package. Repository research files explain the measured section-spacing, comparable anti-slop architecture, authored-versus-used contrast, and non-Latin typography decisions behind the skill.