Kortix brand kit

One kit. It replaces four skills that drifted. It holds the verbal rules, the visual rules, the one values file and the decision history. Read the files for your job. You do not need all of them.

1. Read references/magic_trick.md first

Product screen, mobile screen, product state (empty, error, toast, confirm, loading) or CLI output: skip this file. It needs no artifact and no TODO(idea). Go to section 2 (Q1, Q22).

For every other job, read it before any file in section 2: magic_trick.md states what the work shows: one real artifact the reader keeps. Status: draft, founder confirmation OPEN (D8e in decisions.md). Follow its rules. Add no new idea. Its artifact rule covers marketing, deck, social and launch email. An OG card is the one exception: symbol plus title (Q26).

2. Name the job, then read its row

Paths are relative to references/. "Read" lists files in this kit. "Also load" lists other skills or repo files. Read every file in the row. The "Also load" skill adds components. It does not replace a file in the row (Q2).

Job	Read in this kit	Also load (other skill)
Copy of any kind	voice-and-tone.md, claims.md, positioning.md for headlines and pitches, concepts.md for long-form	none
Product screen (web)	color.md, typography.md, layout.md (including Shells and States), effects.md, motion.md, voice-and-tone.md section 4 (labels and microcopy), claims.md when the copy states a capability	kortix-design-system for components, then the closest reference implementation it names. Read that file before you write JSX. A new page uses the current shell named in layout.md Shells (Q23).
Mobile screen	the same visual files (use each file's mobile column), voice-and-tone.md section 4	apps/mobile/design.md, apps/mobile/AGENTS.md (sections Loading, Icons and the hit-target rule), components/kortix/settings-list.tsx and packages/ui/src/primitives/switch.tsx for a settings screen. Look in apps/mobile/app/ for the screen before you create one: a Notifications screen ships at app/(settings)/notifications.tsx. Product data (event types, defaults, labels) comes from the shipped store or screen, never from this kit. If it is absent, use a named placeholder and list it under Guesses (Q38).
Product microcopy (error, empty, toast, confirm)	voice-and-tone.md section 4, claims.md, layout.md sections Shells and States, color.md (status table: the hue of a refusal or failure), typography.md (mono for literal text, such as a details fold), motion.md (a disclosure fold). This row is complete for an error or empty state on a page: do not also read the Product screen row.	EmptyState (packages/ui/src/primitives/empty-state.tsx), ErrorState (packages/ui/src/primitives/error-state.tsx) and the toast helpers in kortix-design-system. Deliver TSX that renders them, with the strings inline. Return no second file: integration notes go in your reply. Deliver copy only when the person asks for copy only (Q3, Q26).
CLI output and help	voice-and-tone.md section 5.4, claims.md when the text states a capability, color.md (CLI rule), brandmark.md (banner: the landing screen only)	The real binary is the source. Run kortix <command> --help or read apps/cli/src/commands/<command>.ts and apps/cli/src/style.ts, and quote it. Never write a subcommand, flag or value from memory (Q37). Deliver plain text, .txt, unless the person asks for source (Q56).
Email (transactional)	voice-and-tone.md section 5.5, color.md (email rule), typography.md (email rule), brandmark.md (hosted logo PNG and its height), layout.md (Email layout), tokens.css	none. No script checks email: audit.sh does not apply. Check every color with grep -ohE '#[0-9a-fA-F]{6}\b' <file> | sort -u: each hex must appear in tokens.css. Email ships light only (Q34).
Email (launch or announcement)	the transactional row, plus voice-and-tone.md section 5.5b, claims.md, magic_trick.md	none
Landing hero	positioning.md section 1 (approved lines), magic_trick.md, layout.md, typography.md, claims.md	Nearest shipped hero: apps/web/src/features/marketing/landing/content.ts and the hero component it feeds
Landing or marketing section	positioning.md (for security or IT buyers, the Enterprise pitch in section 5: the Promise, then one Mechanism), concepts.md, voice-and-tone.md, claims.md, color.md, typography.md, layout.md (marketing column and Marketing section) and motion.md, graphic-elements.md, magic_trick.md	The page's content.ts under apps/web/src/features/marketing/. A request for "one HTML section" is this row plus the Standalone HTML row.
Deck or film	concepts.md, claims.md, voice-and-tone.md section 5.8 (slide and note copy), layout.md (deck column), typography.md, color.md, motion.md (Deck), brandmark.md. Run scripts/audit.sh on every deck TSX file.	kortix-presentation. Start in this row, not in the recipe skill. Reuse an engine diagram. If it carries a retired claim, fix it in the engine and do not fork it (Q28). The caption arrays inside engine/diagram.tsx are slide copy: check every caption of the diagram you reuse against claims.md, not only the notes (Q46).
Social post	voice-and-tone.md section 5.9, positioning.md, claims.md, art-direction.md (image sizes only)	kortix-social for platform limits. If it is not installed, the kit row is complete: use the limits in section 5.9 and do not search for it.
Image	art-direction.md, brandmark.md, color.md	kortix-image
OG card	art-direction.md (OG and share cards), brandmark.md, color.md, typography.md, tokens.css	kortix-image. Read no file from references/verbal/: the title is the page label. When silent: build a standalone HTML card from tokens.css in --font-sans-system (D8a), then screenshot it at 1200 x 630. Use banner.png only as the fallback.
Anything with the logo	brandmark.md	none
React UI outside apps/web (a Kortix App, a white-label host, an SDK customer app)	the Product screen (web) row	kortix-ui, the skill that ships with @kortix/ui: setup, which component, white-label theming. Compose @kortix/ui components; never copy one or write a second component set (K9).
Standalone HTML without React, outside apps/web (a plain page, a dashboard)	tokens.css, fonts.css (Kortix-owned surfaces only: use --font-sans-system elsewhere), kit.css (the components as k-* classes: compose them before you write CSS), plus the rows above	none. audit.sh does not read HTML: use the checks in section 6. Link fonts.css, tokens.css and kit.css in that order by a path relative to the file, and copy them beside the page when the file leaves the repo. Set no data-theme attribute: tokens.css follows prefers-color-scheme (Q52).
Review of a diff or a draft	the rows for its job, then run scripts/audit.sh <paths>	none

Rule. Besides the row, you may read magic_trick.md (artifact jobs), decisions.md, scripts/audit.sh and any file an "Also load" entry names. — Why: these are sanctioned reads. The R score does not count them (Q22). — Where: every surface. — When silent: read nothing else.

Rule. If a file or skill named in "Also load" is not installed, the row is complete. Do not search the disk for it. — Why: a run read a file from another session's worktree and broke isolation (Q22). — Where: every surface. — When silent: skip it. List it under "Guesses" only if the row cannot be done without it.

Rule. Do not read references/qa/. — Why: it is the rubric for kit maintainers. A job that reads it tests itself against the rubric (Q22). — Where: every surface. — When silent: skip it.

3. The values file

references/visual/visual-system.json is the only file with values. scripts/generate-tokens.ts turns it into the CSS tokens in apps/web/src/app/globals.css (the :root and .dark region), packages/ui/src/styles/theme.css (the kortix-brand theme region inside @theme inline), packages/ui/src/styles/tokens.css and packages/ui/src/styles/fonts.css (whole files), apps/mobile/global.css, references/visual/tokens.css, references/visual/fonts.css and apps/api/src/lib/email/brand-tokens.generated.ts (the email palette and layout). Guidance files cite token names, never a color literal. Never edit a generated region by hand.

4. Order of rules

Rule. When two rules conflict, the newest entry in references/decisions.md wins. — Why: the history records which rule replaced which. — Where: every surface. — When silent: use the rule's "When silent" line and list the choice under "Guesses". An entry marked OPEN has no answer: do not invent one.

Rule. When a skill and this kit disagree, the kit wins on values and on motion restraint. kortix-design-system wins on components. make-interfaces-feel-better (if installed) wins on polish, below the kit's motion ceiling. — Why: a polish skill can suggest motion that the frequency ladder forbids. — Where: app | marketing | mobile. — When silent: take the stricter rule.

Rule. When a request conflicts with this kit, flag the conflict and offer the closest on-message alternative. — Why: a silent override puts off-brand work in front of a customer. — Where: every surface. — When silent: ask a person who owns the brand.

Rule. A claim you cannot trace to verbal/claims.md is not a claim you may make. — Why: every claim is checked against code or a page gate. — Where: every surface. — When silent: leave the claim out.

Priority order and the five passes live in visual/color.md. Each guidance file states its rules as: Rule. — Why: — Where: — When silent:.

5. When the kit is silent

1. Pick the nearest existing token, component, word or claim. The most-used one wins.
2. List the choice under "Guesses" in your output. Name the file you expected to hold the answer. List every className override of a shared component, and every artifact gap in the form magic_trick.md gives.
3. Never invent a value, a word, a metaphor or a claim.

6. Check your work

• Product code and deck TSX: run .agents/skills/kortix-brand/scripts/audit.sh <your paths> yourself. New violations fail the review. audit.sh covers color, spacing and motion values only. It does not check type role, component choice or copy: the files in your row do. Pre-existing hits in a touched file (legacy debt) are listed in the PR body and are not fixed unless asked. Without a path the script audits apps/web/src and reports the legacy debt. It reads .ts, .tsx and .css, so it also checks NativeWind class names in apps/mobile TSX, and it covers the /design-system route. A line that only names a banned token (a styleguide data row) or inlines tokens.css for a page under a CSP carries audit:allow <reason> (Q35).
• HTML (a standalone page, an OG card, a marketing section file): audit.sh does not read HTML. Run grep -nE '#[0-9a-fA-F]{3,8}\b|rgba?\(|hsla?\(|oklch\(' <file.html>. It must print nothing, because HTML takes var(--*) from tokens.css. Email is the exception: use the hex check in its row.
• Copy: grep your text against the don't-say list in voice-and-tone.md and run the claim test in claims.md.
• Light and dark: toggle the theme. Do not read the code and assume. For HTML that links tokens.css, open the file in agent-browser, take a screenshot, run document.documentElement.dataset.theme = 'dark', and take a second one.
• Fresh-agent test (for kit maintainers only: a job never reads it, Q22): references/qa/fresh-agent.md.

7. Change the kit

1. Edit references/visual/visual-system.json.
2. Run bun .agents/skills/kortix-brand/scripts/generate-tokens.ts. It rewrites the three generated files.
3. Update the guidance file that explains the value.
4. Add an entry to references/decisions.md: date, decision, why, where, supersedes, source.
5. Check /design-system and the components that use the value, in light and dark.
6. Run cd tests && npx vitest run --config unit/vitest.config.ts unit/brand-kit.test.ts. It fails on token drift, a color literal in guidance, a broken link or anchor, a decision id with no heading, a cited deleted skill name and a dead duration utility.

8. Related

Need	Where
Which web component to compose, banned primitives, reference implementations	kortix-design-system
Mobile primitives and screens	apps/mobile/design.md, apps/mobile/AGENTS.md
Image, deck and social procedures	kortix-image, kortix-presentation, kortix-social
How a person asks an agent to use this kit	references/how-to-prompt.md
Live styleguide	the /design-system route in apps/web
Canonical logo files	apps/web/public/brandkit/