kortix-brand
Load FIRST for anything that carries the Kortix look or voice: product or mobile UI, copy of any kind, decks, social, images, email, CLI output, anything with the logo, and reviews of these. Routes yo
SKILL.md.agents/skills/kortix-brand/SKILL.md
GitHubKortix 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
- Pick the nearest existing token, component, word or claim. The most-used one wins.
- List the choice under "Guesses" in your output. Name the file you expected to hold the answer. List every
classNameoverride of a shared component, and every artifact gap in the form magic_trick.md gives. - 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.shcovers 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 auditsapps/web/srcand reports the legacy debt. It reads.ts,.tsxand.css, so it also checks NativeWind class names inapps/mobileTSX, and it covers the/design-systemroute. A line that only names a banned token (a styleguide data row) or inlinestokens.cssfor a page under a CSP carriesaudit:allow <reason>(Q35). - HTML (a standalone page, an OG card, a marketing section file):
audit.shdoes not read HTML. Rungrep -nE '#[0-9a-fA-F]{3,8}\b|rgba?\(|hsla?\(|oklch\(' <file.html>. It must print nothing, because HTML takesvar(--*)fromtokens.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 inagent-browser, take a screenshot, rundocument.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
- Edit
references/visual/visual-system.json. - Run
bun .agents/skills/kortix-brand/scripts/generate-tokens.ts. It rewrites the three generated files. - Update the guidance file that explains the value.
- Add an entry to references/decisions.md: date, decision, why, where, supersedes, source.
- Check
/design-systemand the components that use the value, in light and dark. - 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: tokens measured live, light beside dark, every component as a Spec. Open it before you build a product screen |
| Structural patterns: parallel slots, one name plus an info icon, the four states, hover is color only | kortix-design-system references/patterns.md; every job → class → token in token-map.md |
| Canonical logo files | apps/web/public/brandkit/ |
| Merch print files: playing cards, chips, flags, posters, mugs, mats, totes, tees, a sticker pack, pin buttons, and the script that draws them | references/merch/README.md |