Find Designs

Browse Commons (joincommons.cc) to find a distinctive design identity for the user's project, then apply it as the project's design system.

Rules

Phase 0 (project scan) is COMPLETELY SILENT. Never tell the user what files you found.
Download thumbnail images locally and show them to the user (see Phase 1B).
This should feel like a conversation, not a tutorial. Don't dump walls of text.
Read DESIGN.md and SKILL.md only AFTER the user picks a skill (not before).

Phase 0 — Initialize (silent)

Scan silently — do NOT output any of this:

package.json / tech stack
Existing CSS, Tailwind config, theme files, design tokens
Product type (dashboard, landing page, SaaS, blog, etc.)
Target audience

Check for existing taste profile:

.commons/taste.json (project-level)
~/.commons/global-taste.json (global)

If taste profile exists, use it to skip or shorten Phase 2.

Say something brief: "I'll help you find a design style. Let me look at your project..."

Phase 1 — Search & Download Previews

1A: Search Commons

Construct 2-4 search queries based on your scan:

GET https://joincommons.cc/api/items?q={keywords}&limit=10
GET https://joincommons.cc/api/items?sort=trending&limit=10

Key fields to evaluate:

bestFor / avoidFor — product fit (skip if avoidFor matches your project)
coaching.identity — one-sentence design philosophy
coaching.signatureMoves — key visual decisions
cardThumbnailUrl — PNG preview URL
temperature — warm / cool / neutral

1B: Download Thumbnails

After selecting 5 candidates, download their card thumbnails locally so the user can see them:

python skills/find-designs/scripts/download_thumbnails.py --slugs "slug-1,slug-2,slug-3,slug-4,slug-5"

This saves PNGs to .commons/previews/ and outputs JSON with local file paths.

If Python is not available, download manually:

mkdir -p .commons/previews
curl -sL "{cardThumbnailUrl}" -o .commons/previews/{slug}-card.png

Then show the downloaded images to the user. Reference the local file paths (e.g., .commons/previews/pencil-draft-card.png).

If you cannot display local files, show the CDN URL as a clickable link: https://pub-962ae6531eaf4fc2b3cd95edcb026436.r2.dev/thumbnails/ai-{slug}-card.png

Phase 2 — Taste Convergence

Two rounds. Do not collapse into one.

Round 1: Wide Exploration (5 options)

Pick 5 STYLISTICALLY DIVERSE candidates. For each show:

The downloaded thumbnail image (from .commons/previews/)
Name
One-line identity
2-3 signature moves

Ask: "Which feel right? Which feel wrong?"

If user picks one directly → skip Round 2.

Round 2: Narrow Refinement (3 options)

Based on Round 1 feedback, show 3 variants within the preferred direction.

Returning user shortcut

If taste profile exists: skip Round 1, present 3 pre-filtered options or recommend 1.

Phase 3 — Save Taste Profile

Save to .commons/taste.json:

{
  "version": 1,
  "updated_at": "<ISO>",
  "preferences": {
    "temperature": "warm | cool | neutral",
    "density": "spacious | balanced | compact",
    "radius": "sharp | moderate | rounded",
    "font_tendency": "serif | sans | mono | mixed",
    "personality": "minimal | professional | playful | bold | organic"
  },
  "liked_skills": [],
  "disliked_skills": [],
  "selected_skill": "<slug>",
  "feedback_notes": []
}

Also merge into ~/.commons/global-taste.json if writable.

Phase 4 — Preview

Pick 1-2 existing project pages
Fetch: GET https://joincommons.cc/api/items/{slug}
Read designLanguageUrl (DESIGN.md)
Apply colors, typography, spacing to the page in preview mode
Ask: "Here's how it would look. Proceed or try a different skill?"

Phase 5 — Install

Download artifacts

From the detail response (GET /api/items/{slug}), save:

designSkillUrl → .commons/SKILL.md
designLanguageUrl → .commons/DESIGN.md
tokensDtcgUrl → .commons/tokens.dtcg.json

Track the install

POST https://joincommons.cc/api/items/{slug}/apply
Content-Type: application/json
Body: { "source": "skill", "agent_id": "<your-agent-id>" }

Generate framework tokens

Based on tech stack:

Tailwind: Map to CSS custom properties + tailwind.config.ts theme.extend
CSS Variables: Generate :root {} block
styled-components: Generate theme object

Apply the design language

Read .commons/SKILL.md — it has specific instructions. Follow it first. Then:

Update global styles
Apply signature moves
Respect hard constraints
Avoid anti-patterns

Phase 6 — Fine-Tuning

Proactively offer: "Want to tweak anything? 'Make the primary color warmer', 'reduce border radius', 'use a serif font'."

Loop until user says "looks good" or "done". Update taste profile with every tweak.

Phase 7 — Report

Summarize: skill applied, key decisions, files modified, link to https://joincommons.cc/style/{slug}.

API Reference

GET  /api/items              — list (?q=, ?sort=trending|new|most-applied, ?limit=)
GET  /api/items/{slug}       — detail + artifact URLs
POST /api/items/{slug}/apply — track install

Context Window Management

Phase 0-2: list metadata only. Do NOT fetch DESIGN.md.
Phase 4: fetch DESIGN.md only for the chosen skill.
Phase 5: fetch SKILL.md + DESIGN.md + tokens only during install.

find-designs