Specs’ own brand kit. Same format it makes for you.

---
chunk_id: readme
domain: routing
depends_on: []
token_count: 520
confidence: high
sources:
  - upload: docs/spec.md
    location: Brand kit format; "The app's own brand"
version: 1
summary: >-
  Routing file for Specs' own brand kit: the app describing itself in the same
  format it makes for other brands, and which chunks to read for each job.
---

# Specs brand kit

Specs is a free, open-source web app that turns a small business's messy brand materials into a brand kit an AI can read, then art-directs Instagram posts that explain their own design decisions. This is its own kit, written in the format it generates, so the method is visible in the tool itself.

Unlike the three demo brands, Specs is real. The facts here are true as of the version date.

## Chunks

| Chunk | Holds |
| --- | --- |
| `positioning-core.yaml` | What Specs is, who it's for, the promise, differentiators, and the only facts copy may use |
| `brand-about.md` | Plain-language description and how a session works |
| `audience-designers.yaml` | The core audience: designers and creative leads judging AI design tools |
| `voice-core.md` | How Specs sounds, built on "Your brand, written down for machines." |
| `voice-examples.md` | Lines from the app, sample lines per post intent, do / don't pairs |
| `terminology.yaml` | Words to use and avoid, with reasons |
| `visual-system.json` | "Quiet room. Loud brand.": colors, contrast limits, type roles, shape and spacing |
| `tokens.css` | Generated from visual-system (`npm run tokens -- specs`); don't edit |
| `art-direction.md` | Screens as the subject, the brand being built as the only color |
| `social-rules.md` | Sizes, slot lengths, CTA and hashtag style, template per intent |
| `guardrails.yaml` | What never to say or show |
| `_retrieval-rules.yaml` | Which chunks load for each job |

## Which to read

- **Writing a post or page copy:** voice-core, visual-system, art-direction, social-rules, terminology; add positioning-core whenever the copy states a number, model or limit.
- **Critiquing:** voice-core, art-direction, guardrails, social-rules.
- **Finding gaps:** this file plus every chunk's summary; open anything marked `medium`.

## Sources

`docs/spec.md` (the product), `app/globals.css` (the look, as built), `docs/journal.md` (decisions and why), `core/config.ts` and `core/limits.ts` (models and caps), and the look agreed with Scott Galetto on 2026-11-04 ("Quiet room. Loud brand.").

chunk_id: positioning-core
domain: positioning
depends_on: []
token_count: 560
confidence: high
sources:
  - upload: docs/spec.md
    location: Overview (pitch, positioning, goals, non-goals)
  - upload: CLAUDE.md
    location: Decisions already made
  - upload: core/limits.ts
    location: session and cost caps
version: 1
summary: >-
  Specs is the art director's version of AI brand tools: it turns messy brand
  materials into a kit an AI can read and posts that show their reasoning.
  Free, open source, a portfolio piece by Scott Galetto.
---
what_it_is: >-
  A web app. Upload a logo, website, a PDF and a few photos; watch a brand kit
  assemble with every item tagged to the upload it came from; answer a few
  questions about what's missing; get Instagram posts that each explain why
  they look the way they do. Take the kit with you as a folder of small files.
why_it_exists: >-
  AI tools already make on-brand posts from a URL, but they don't show their
  work. Specs makes the brand understanding visible, editable and traceable to
  its sources, and puts the reasoning on every post.

who_its_for: >-
  Designers and creative leads judging what AI can do for brand work, and
  small business owners who want a kit they can reuse in any AI tool. Detail
  in audience-designers.

promise: Your brand, written down for machines.
promise_reason: >-
  A brand kit used to be a PDF for people. Agents need small, sourced files
  they can load one at a time. Specs writes those, and shows them working.

differentiators:
  - name: Shows its work
    detail: Every post has a "Why this works" layer that pins each choice to the kit rule behind it.
  - name: Traceable
    detail: Every item in the kit names the upload it came from. Conflicts between uploads are asked about, not guessed.
  - name: Portable
    detail: The kit downloads as a zip of plain Markdown, YAML and JSON. It works in any AI tool.
  - name: With and without
    detail: Each post can flip to the same brief made with no kit, so the difference is visible.

facts:
  note: Copy may use only these facts. They're true as of version 1.
  name: Specs
  url: specs.humanbuiltai.work
  maker: Scott Galetto
  license: Code is MIT. The fictional brands, prompts and design assets are all rights reserved.
  price: Free. No accounts.
  formats: Instagram 1:1 and 4:5
  post_intents: [promo, announcement, event, testimonial, tip]
  demo_brands: Three fictional brands (Half Acre Club, Third Shift Slice, Hollis Ware), free to explore with no API calls
  models: Claude Sonnet reads uploads and writes posts; Claude Haiku critiques posts and asks the intake questions
  limits: A live session makes up to 4 posts and asks at most 12 intake questions, under a hard daily cost cap

---
chunk_id: brand-about
domain: positioning
depends_on: [positioning-core]
token_count: 430
confidence: high
sources:
  - upload: docs/spec.md
    location: User flow (five screens)
  - upload: docs/journal.md
    location: phases 2 to 6
version: 1
summary: >-
  What Specs does, in plain language, and the five steps of a session: start,
  upload, the reveal, fill the gaps, make posts.
---

# About Specs

Specs reads the brand materials a small business already has, the logo, the website, an old flyer, phone photos, and writes down what makes the brand itself: who it's for, how it sounds, its colors and type, what it would never say. It writes that down as a brand kit, a folder of small files an AI can load one at a time, each with the upload it came from.

Then it uses the kit to make Instagram posts, and every post shows its reasoning.

## A session

1. **Start.** Pick a demo brand to see finished posts right away, or start with your own materials.
2. **Upload.** A logo, a website address, one PDF, up to five photos, and a note for anything else.
3. **The reveal.** The kit assembles on screen as it's read. Colors come from the photos, voice from the words, each item tagged with its source. Edit or delete anything.
4. **Fill the gaps.** Specs asks about what's missing or contradictory, one question at a time, using small purpose-built controls: pick a palette, place a tone on a dial, choose which line sounds like you.
5. **Make posts.** Pick what the post is for and fill a short brief. Each post comes with "Why this works", a with-kit / without-kit toggle and a PNG download. The kit downloads here too.

## Why it's built this way

Posts render from HTML templates filled with the kit's tokens, not from image generation, so fonts, colors and logos come out exact. The kit is plain text so it outlives the app.

chunk_id: audience-designers
domain: audience
depends_on: [positioning-core]
token_count: 360
confidence: medium
sources:
  - upload: docs/spec.md
    location: Goals ("posts a working designer would be comfortable showing a client"; "a clear case study of AI experience design")
  - upload: docs/journal.md
    location: phase 2 gate (blind pick by designer friends)
version: 1
summary: >-
  The core audience: designers, art directors and creative leads deciding
  whether AI can be trusted with brand work. They judge craft first and are
  allergic to hype. Small business owners are a second audience.
---
segment: Designers and creative leads judging AI for brand work
includes: [brand and visual designers, art directors, design managers, people hiring for AI design roles]

situation:
  - Have seen a lot of AI output that is on-trend and off-brand
  - Judge a tool by its worst post, not its best
  - Read type, spacing and color before they read the copy
  - Will look at the repo and the prompts if the work is good

wants:
  - Output they'd show a client without apologizing
  - To see why the AI made each choice, so they can argue with it
  - Control over the inputs, not a slot machine
  - A method they can reuse in their own work

barriers:
  - Hype words ("magic", "revolutionary") read as a tell that the work is weak
  - Generic AI look (gradients, glow, purple) reads as a template
  - Black-box output with no source for its claims

what_wins_them:
  - The with / without kit toggle on a real brief
  - A "Why this works" note that cites a rule they agree with
  - Small, careful UI that stays out of the brand's way

second_audience:
  segment: Small business owners
  wants: A kit they can paste into any AI tool so the output sounds like them
  note: Same voice; explain terms like "brand kit" in one plain line.

---
chunk_id: voice-core
domain: voice
depends_on: [positioning-core]
token_count: 520
confidence: high
sources:
  - upload: app/page.tsx
    location: headline "Your brand, written down for machines."
  - upload: app/ui/catalog/
    location: interface copy (one sentence per intake turn, "needs your call")
  - upload: CLAUDE.md
    location: '"Rules inside chunks state the reason, not just the rule. Prefer concrete examples over adjectives."'
version: 1
summary: >-
  An art director talking to a client: plain, exact, a little dry. Says what
  it did and why, in short sentences. No hype, no exclamation marks, no
  "magic". The work is the proof.
---

# Voice core

**The reference line:** "Your brand, written down for machines."

Plain words, one idea, slightly surprising. Every rule below explains why that works.

## Rules

1. **Say what it does, then why.** "Each post shows the rule behind it." The reason is the product, so the reason goes in the copy.
2. **Short and finished.** One idea per sentence. The app asks one question per turn in one sentence, and the copy follows the same discipline.
3. **Concrete over adjectives.** "Five files: voice, audience, colors, rules, guardrails" beats "a powerful brand toolkit". Name the thing.
4. **Dry, not cute.** A small turn of phrase is fine ("Quiet room. Loud brand."). Puns, wink emoji and mascots are not.
5. **Credit the inputs.** Say "from your photos" and "from your About page". The point is that nothing comes from nowhere.
6. **Honest about limits.** "Up to four posts." "Fictional brands." "About $0.30 in API calls." Numbers build trust with designers.
7. **Sentence case, no exclamation marks.** Calm reads as confident.

## Calibration

| Too far one way | On voice | Too far the other way |
| --- | --- | --- |
| "Unleash your brand's magic with AI-powered creativity! ✨" | "Your brand, written down for machines." | "Brand kit generation utility v1. Upload assets to begin." |
| Hype, sparkle, nothing specific | Plain, specific, a little dry | Manual, no person, no point of view |

## Never

- "Magic", "unleash", "supercharge", "revolutionary", "effortless", "AI-powered".
- Exclamation marks and emoji.
- Claims without a source, which is the one thing the product exists to prevent.

---
chunk_id: voice-examples
domain: voice
depends_on: [voice-core]
token_count: 480
confidence: high
sources:
  - upload: app/page.tsx
    location: start screen copy
  - upload: app/posts/[brand]/page.tsx
    location: posts page copy
  - upload: app/ui/catalog/
    location: intake and error copy
version: 1
summary: >-
  Real lines from the app, sample lines for each post intent, and do / don't
  pairs, so a writer can hear the voice before writing.
---

# Voice examples

## Lines from the app

- "Your brand, written down for machines."
- "Pick a demo brand to see finished posts."
- "Each post shows why it works, and the same brief made with no kit."
- "Drop the folder into any AI tool, or hand it to a freelancer."
- "The zip didn't build. Try again."
- Signal red means one thing: "This needs your call."

## Sample lines per intent

| Intent | Headline | Supporting line |
| --- | --- | --- |
| Announcement | Specs is live. | Upload your brand. Get posts that explain themselves. |
| Promo | See the difference. | Same brief, with and without a brand kit. |
| Tip | Write the reason, not just the rule. | "No exclamation marks" is a rule. "Calm reads as confident" is a reason an AI can follow. |
| Event | Demo night. | Three fictional brands, start to finished posts. |
| Testimonial | (Use only a quote the brief supplies, word for word.) | |

## Do / don't

| Do | Don't |
| --- | --- |
| "Every item names the upload it came from." | "Powered by cutting-edge AI." |
| "The photo says Box 014. The notes say Box 01. Which is right?" | "Oops! Something looks off 🤔" |
| "Free. No accounts." | "Get started for free today!" |
| "Posts render from templates, so your fonts come out exact." | "Pixel-perfect magic every time." |

chunk_id: terminology
domain: voice
depends_on: [voice-core, positioning-core]
token_count: 380
confidence: high
sources:
  - upload: docs/spec.md
    location: Brand kit format; user flow names
  - upload: core/catalog.ts
    location: component names
version: 1
summary: >-
  Words Specs uses (brand kit, chunk, source, why this works, needs your call)
  and words it avoids (magic, AI-powered, assets, content, seamless).
---
use:
  - term: Specs
    note: Always capitalized, never "SPECS" or "Specs AI".
  - term: brand kit
    instead_of: [brand book, style guide, brand assets]
    why: It's a working set of files, not a document to read once.
    note: For owners, explain it once as "a folder of small files an AI can read".
  - term: chunk
    note: Fine with designers and in the repo; say "file" or "part of the kit" to owners.
  - term: source
    why: Every claim has one. Say "from your About page", not "detected".
  - term: Why this works
    note: The name of the reasoning layer on posts. Title case only as a button label.
  - term: with kit / without kit
    why: The comparison is the argument. Keep the words exactly.
  - term: needs your call
    note: The only thing signal red ever means.
  - term: post
    instead_of: [content, creative, asset]
    why: It's an Instagram post. Say so.

avoid:
  - term: magic
    why: The point is that nothing is magic; every choice has a reason.
  - term: AI-powered
    why: Everyone is. Say what it does.
  - term: seamless, effortless, unleash, supercharge
    why: Hype words read as a tell to designers.
  - term: generate (in user-facing copy)
    instead_of_use: make, write, draft
    why: "Make posts" sounds like a person at work; "generate content" sounds like a machine.

{
  "meta": {
    "chunk_id": "visual-system",
    "domain": "visual",
    "depends_on": ["positioning-core"],
    "token_count": 780,
    "confidence": "high",
    "sources": [
      { "upload": "app/globals.css", "location": ":root tokens (light and dark)" },
      { "upload": "docs/journal.md", "location": "2026-11-04, phase 5 step 1: the look agreed with Scott" }
    ],
    "version": 1,
    "summary": "Quiet room. Loud brand. A light gray table, white cards, black Geist type, and no color of its own except one signal red that means 'this needs your call'. The brand being built is the only color on screen."
  },
  "concept": "Quiet room. Loud brand. Specs is the gallery wall, not the painting: gray table, white cards, black type, so the brand on screen is the loudest thing in the room.",
  "color": {
    "canvas": {
      "hex": "#ECECEA",
      "name": "Table gray",
      "role": "Page background: the table the cards sit on.",
      "rule": "Always the background. It's slightly warm so photos and brand colors don't look clinical on it."
    },
    "surface": {
      "hex": "#FFFFFF",
      "name": "Card white",
      "role": "Cards, inputs, anything you can pick up.",
      "rule": "White means 'an object'. Never use it as a page background."
    },
    "ink": {
      "hex": "#0E0E0F",
      "name": "Ink",
      "role": "All primary text, buttons, selected states.",
      "rule": "16.3:1 on canvas, 19.3:1 on white. Selected things turn ink, not a color."
    },
    "gray": {
      "hex": "#68686C",
      "name": "Pencil gray",
      "role": "Secondary text: captions, labels, the second half of a headline.",
      "rule": "4.7:1 on canvas, 5.6:1 on white, so it's safe for small text. Was #8C8C8F until v1 of this kit found it fell short of 4.5:1 for small text."
    },
    "signal": {
      "hex": "#FF3B1F",
      "name": "Signal red",
      "role": "The dot in the wordmark, needs-review marks, focus rings, the intake's one flag.",
      "rule": "Means only 'this needs your call'. 3.0:1 on canvas and 3.6:1 on white, so it's for marks, rings and type 18px and up; small red text uses Signal ink (#C42812, 4.9:1 on canvas) instead. Never decoration, never a button fill."
    }
  },
  "dark_mode": {
    "note": "Same rules, inverted room. Follows the system; a switch in the top bar overrides it.",
    "canvas": "#0D0D0E",
    "surface": "#1A1A1C",
    "ink": "#F3F3F1",
    "gray": "#8E8E93",
    "signal": "#FF5236"
  },
  "pairings": {
    "allowed": [["ink", "canvas"], ["ink", "surface"], ["gray", "surface"], ["gray", "canvas"], ["surface", "ink"]],
    "avoid": [
      { "pair": ["surface", "signal"], "reason": "A red button turns the one alarm color into a call to action." },
      { "pair": ["signal", "gray"], "reason": "Red text on gray is low contrast and reads as an error everywhere." }
    ]
  },
  "roles": {
    "note": "Maps the shared post templates' color roles to Specs' colors, so the app can make posts about itself.",
    "background": "canvas",
    "text": "ink",
    "heading": "ink",
    "accent": "signal",
    "wordmark": "ink",
    "label": "surface"
  },
  "type": {
    "wordmark": {
      "description": "'Specs' in Geist bold, tight, followed by a small signal-red dot.",
      "stand_in_font": "Geist",
      "weight": 700,
      "letter_spacing": "-0.04em",
      "case": "as written",
      "lockup": ["Specs"],
      "rule": "The dot is the only color in the mark. Never a period in another color, never an icon.",
      "confidence": "high"
    },
    "heading": {
      "stand_in_font": "Geist",
      "weight": 600,
      "color": "ink",
      "min_px_at_1080": 72,
      "letter_spacing": "-0.05em",
      "description": "Tight Swiss grotesk, sentence case, big. The second half of a headline often drops to gray: 'Your brand, written down for machines.'",
      "confidence": "high"
    },
    "body": {
      "description": "Geist regular, plain and readable.",
      "stand_in_font": "Geist",
      "weight": 400,
      "color": "ink",
      "min_px_at_1080": 30,
      "line_height": 1.5,
      "confidence": "high"
    },
    "hand": {
      "description": "Not handwriting: Geist Mono for evidence, like chunk IDs, sources, counts and eyebrows.",
      "stand_in_font": "Geist Mono",
      "weight": 400,
      "color": "gray",
      "min_px_at_1080": 28,
      "rule": "Mono means 'this is data you can check'. Use it for sources and IDs, never for headlines.",
      "confidence": "high"
    }
  },
  "shape": {
    "radius_px": 28,
    "stamp_rotation_deg": 0,
    "rule": "Big soft corners on cards (28px), 16px inside them, pills for buttons. Nothing rotated."
  },
  "spacing": {
    "safe_margin_px_at_1080": 72,
    "unit_px": 4
  }
}

---
chunk_id: art-direction
domain: visual
depends_on: [positioning-core, visual-system]
token_count: 470
confidence: medium
sources:
  - upload: docs/journal.md
    location: 2026-11-04, phase 5 step 1 (Scott's references; "an art director's dream")
  - upload: app/page.tsx
    location: start screen demo cards
version: 1
summary: >-
  The subject is always someone else's brand on Specs' quiet screens: real
  screenshots, posts with their pins showing, kits as files. No stock photos,
  no robots, no glowing gradients.
---

# Art direction

## The subject

Specs has no product photos. Its pictures are its screens, and the brand in them is someone else's. The reason: the whole idea is that Specs gets out of the way so a brand can be loud. A picture of Specs should prove that.

- **Show real output.** A screenshot of a post with "Why this works" pinned on it, the with / without toggle mid-flip, a kit folder open in a code editor. Crop tight, at 2× so type stays sharp.
- **Let the demo brands bring the color.** The pea green of Half Acre Club, the neon of Third Shift Slice, the clay of Hollis Ware. Specs' gray and white frame them.
- **Evidence in mono.** When a picture needs a label, set it like a source tag: `voice-core`, `from: about-us.pdf`.

## The three reference shots

1. **The start screen:** three demo cards, each in its own brand's colors, on the gray table. Three loud brands, one quiet room.
2. **A pinned post:** a Third Shift Slice post with numbered pins in the margin and the notes below, citing chunk IDs.
3. **With / without:** the same brief side by side; the kit version clearly better without a word of explanation.

## Never

- Stock photos of laptops, offices or hands on keyboards.
- Robots, brains, sparkles, glowing orbs or purple-to-blue gradients: the generic AI look the audience distrusts.
- Specs' own red used as decoration. If it's red, something needs a decision.

---
chunk_id: social-rules
domain: social
depends_on: [voice-core, visual-system, art-direction]
token_count: 420
confidence: medium
sources:
  - upload: docs/spec.md
    location: scope (Instagram 1:1 and 4:5; five post intents; six templates)
version: 1
summary: >-
  Instagram sizes, slot lengths, CTA and hashtag style, and the template for
  each post intent when Specs posts about itself.
---

# Social rules

Drafted for when Specs posts about itself; tune once real posts render.

## Sizes

- **4:5** at 1080 × 1350 for screenshots and announcements.
- **1:1** at 1080 × 1080 for type-led tips.
- Keep 72px clear on every edge.

## Slot lengths

| Slot | Limit | Why |
| --- | --- | --- |
| Headline | 7 words, 42 characters | "Your brand, written down for machines." |
| Subhead | 90 characters | One concrete sentence: what it does or why. |
| CTA | 3 words | "Try a demo." "Read the kit." No exclamation marks. |
| Badge / label | 16 characters, mono | A source tag or chunk ID, never a price. |
| Caption | 2–4 sentences, under 400 characters | Ends with the URL. |

## CTA style

Say where and what: "Try a demo at specs.humanbuiltai.work." Never "Sign up now" (there are no accounts) or "Link in bio!".

## Hashtags

None, or one (`#branddesign`). Never a block.

## Logo on posts

The wordmark, "Specs" with the red dot, ink on gray, small, bottom corner.

## Template by intent

| Intent | First choice | Why |
| --- | --- | --- |
| Announcement | Photo-led (4:5) with a screenshot | Show it working. |
| Promo | Split | The with-kit post beside the without-kit post. |
| Tip | Type-led (1:1) | One kit-writing idea, set large. |
| Event | Event card | Date and place at a glance. |
| Testimonial | Quote card | Only a quote the brief supplies. |

chunk_id: guardrails
domain: guardrails
depends_on: [positioning-core, voice-core, art-direction]
token_count: 380
confidence: high
sources:
  - upload: CLAUDE.md
    location: Rules (never invent facts; API key handling)
  - upload: docs/spec.md
    location: Non-goals; cost guards
version: 1
summary: >-
  Hard limits for anything Specs says about itself: no invented features,
  users or numbers, no hype, no implying the demo brands are real, and red
  only for decisions.
---
never_say:
  - rule: Facts not in positioning-core
    examples: [user counts, customers, revenue, awards, press, integrations it doesn't have, publishing or scheduling]
    why: A tool about sourced claims can't make unsourced ones about itself.
  - rule: That the demo brands are real businesses
    why: Half Acre Club, Third Shift Slice and Hollis Ware are fictional. Say so wherever they appear.
  - rule: Features from the spec's non-goals as if they exist
    examples: [accounts, saved projects, teams, video export, paid plans, formats beyond Instagram 1:1 and 4:5]
    why: They're not built. Saying "coming soon" is fine only if the spec lists it as planned.
  - rule: Hype
    examples: ['"magic"', '"revolutionary"', '"AI-powered"', '"effortless"']
    why: The audience reads hype as a sign the work is weak.
  - rule: A quote or name the brief didn't supply
    why: A made-up quote is a fake review.
  - rule: That Specs replaces designers
    why: It's the art director's version, a starting draft a person checks. Say what it does, not who it replaces.

never_show:
  - Signal red as decoration, a button fill, or a background
  - Generic AI imagery (robots, brains, glowing gradients, sparkles)
  - A demo brand's post without its "fictional" label nearby
  - Rotated or tilted type

when_unsure: >-
  Leave it out and say so in the rationale. Specs would rather show a gap
  than fill it with a guess; that's the product.