Changelog

Release notes of @okrado/brand. Component release notes are in each @okrado/ui release; the stage of every component is on the catalogue.

Changelog

All notable changes to @okrado/brand, in the Keep a Changelog format; versions follow SemVer. Renaming or removing a token is a breaking change.

[Unreleased]

[0.6.0] - 2026-11-03

The overlay and interaction foundation (ADR-0108) and the forced-colors / prefers-contrast layer (ADR-0102).

Added

• Layer tokens ui.z.* (--okr-ui-z-*): sticky 10, sheet 40, dialog 50, popover 60, toast 70, tooltip 80, skip 90, and the Tailwind utilities z-sticky … z-skip.
• Overlay sizes in ui.layout.*: dialog sm/md/lg 440/560/720, drawer sm/md/lg 340/480/640, bottom-sheet snap points 0.5 and 0.9; Tailwind max-w-dialog-md, w-drawer-lg.
• ui.motion.exit-ratio 0.8 and the micro-exit, standard-exit, panel-exit durations.
• ui.css: @media (forced-colors: active) (CanvasText border on [data-elevation="e2|e3"], focus outline) and @media (prefers-contrast: more) (line and muted text one step stronger, in light, dark and system dark).

Changed

• Reduced motion keeps a short opacity fade (principle 7) instead of an instant end state; LANGUAGE.md sections 1, 5, 9 and 13 and the brand.yaml motion principle follow ADR-0108.

[0.5.0] - 2026-11-03

The suite asset system v1 (ADR-0106, ADR-0107): one catalogue, one file per asset, and the views that used to be kept by hand now generated from it. Consumers (Studio, ui) follow in their own PRs.

Added

• Catalogue okrado.brand.catalog/1: catalog/<kind>/<slug>.yaml, one file per asset, ten kinds (identity, icon, graphic, image, type, motion, video, audio, social, template) with an open subkind. Every v0 field is kept; new: altText {en, fr, ar} / decorative, tags, version / supersedes, lifecycle (draft, needs-review, active, deprecated, revoked) with replacedBy and sunset, approval {by, at, pr}, derivatives[], usage, onBackground, digitalSourceType, c2pa, transcriptRef / captionsRef, storage {git, r2, package}, generator, glyph, font.
• Validation (the brand.catalog check, run by the build and the tests): alt text in all three locales unless decorative, licence, AI-generated needs provenance and digitalSourceType, people need consent, active needs approval, deprecated needs replacedBy (an active record) and sunset, an unverified licence is never active, deny-listed icon glyphs are never active, SVGs keep their viewBox and <title> and carry no raw hex (the mark is allow-listed), public R2 keys match the ADR-0107 grammar and the sha256.
• Generated views in dist/: catalog/index.json (+ index.d.ts, the typed index), catalog/<kind>.json, catalog/<kind>/<slug>.json, catalog.ndjson (the Studio’s v0 shape, from the git-stored records) and catalog/fonts-manifest.yaml (replaces the hand-kept fonts/manifest.yaml).
• build/lib/r2.mjs: publicBrandKey derives brand/<kind>/<slug>/<sha256[:12]>.<ext>; npm run r2:keys prints the planned key of every publishable asset. Nothing is uploaded.
• Package exports ./catalog (typed), ./catalog/* (per-kind and per-asset JSON) and ./catalog/fonts-manifest.yaml; ./catalog.ndjson and the rest are unchanged.
• The four web variable faces (Archivo, Inter, JetBrains Mono, Readex Pro) are now catalogue records (type, variable-font) with their package integrity from the lockfile.

Changed

• catalog/assets.yaml (75 records) is split into 75 files; the migration is lossless (a test compares the generated Studio view with the frozen v0 catalog.ndjson, field for field). status is now lifecycle; storage.repo/path is storage.git; r2Key is storage.r2.key. The Studio view maps them back.
• Every migrated active record carries approval.legacy: true (grandfathered by the phase-0 review); the number of legacy approvals may only shrink. Records made by build scripts carry digitalSourceType: algorithmicMedia.
• fonts/manifest.yaml is removed: it is generated into dist/catalog/fonts-manifest.yaml.

[0.4.0] - 2026-11-03

The foundations audit, step 1 (findings 3, 8, 9, 10, 12, 13): the icon set, the head data and the share cards every surface used to assemble by hand now come from this package. Consumers (ui, standard, site, hub, knowledge) follow in their own PRs.

Added

• Complete icon set generated by build/logo.py from the logo construction (standard library only, checked by pixels): favicon.ico (16, 32, 48), icon-192.png, icon-maskable-512.png (full bleed, the ring at 60 % of the width, inside the W3C safe zone of a 40 % circle), and an apple-touch-icon-180.png that is full bleed and opaque (iOS no longer fills transparent corners black). favicon-16/32/48.png and the ico all carry the snapped dark tile (a bare ink glyph is 1.05:1 on night; Safari before 26, crawlers, Windows and unfurlers use them on any background), with the record a whole-pixel square, so its edges are alpha 0 or 255. The 512 px “any” icon is app-icon-512.png.
• dist/web/manifest.webmanifest and dist/web/head.json (okrado.brand.head/0): link tags (svg, ico, png, apple touch, manifest; the ico is declared sizes="32x32" so Chromium keeps preferring the adaptive SVG) with publicFiles (the URL each file is served at, and its source in the package), theme-color for paper and night from ui.bg.canvas with prefers-color-scheme media queries, the social handle from brand.yaml handles, one title pattern, and per locale the tagline, description, og:locale, share image (light and night) and alt text. The web manifest has id, lang, dir and description; a card footer is the locale’s tagline.
• One title pattern for every surface, in brand.yaml head.title: {page} – {brand} (page first, brand last, an en dash with spaces); home is {brand} – {tagline}. It replaces “Okrado · X” (site), “X · Okrado” (template, portal) and the bare product name (hub); it is not a dot-join (lint rule U20).
• A 1200 × 630 OG card per locale in languages.copy.okrado (en, fr): dist/web/og/og-fr-{light,dark}.{html,png} (English keeps og-{light,dark}). Card text and alt text are catalogue data in brand.yaml head.share (real accents, French narrow no-break spaces); ar is listed as pending until its copy exists, and a test refuses a locale in neither place. npm run render:social renders the cards with Chrome from the pinned Fontsource packages.
• Readex Pro (Arabic) in the web font list of fonts/manifest.yaml: @fontsource-variable/readex-pro 5.3.0, OFL-1.1 checked against the package, axes wght 160-700 and HEXP. The ui.font.family.arabic stack now leads with Readex Pro Variable.
• Icon policy: brand.yaml iconStyle is active (it was proposed): Lucide is the only UI set, a video picks one of lucide, ph or tabler. deny lists glyph tokens and names for agents (robots and faces: bot, bot-message-square, smile, scan-face, baby, ghost, skull, drama, venetian-mask …), exposed as dist/web/icons-policy.json. Exports ./web/head.json, ./web/manifest.webmanifest, ./web/icons-policy.json.
• Layout standard v1 tokens: ui.layout.{topbar,icon-rail,sidebar-min,sidebar-max,form-max,dashboard-max,page-inline-sm,page-inline,page-top,section-gap} (48, 48, 200, 320, 640, 1440, 16, 24, 24, 32 px), ui.layout.reading-max (68ch) and ui.layout.header-toolbar-gap (12 px), ui.nav.item (28 compact, 32 comfortable, 44 on coarse pointers) and ui.row.height-2line (56 px); ADR-0083. dashboard-max applies to dashboards only, data pages are fluid; the app shell sets compact density, :root stays comfortable.

Changed

• LANGUAGE.md §10: the sidebar item is 32 px (it was an off-grid 30); dates render Inter tabular, mono only for ledger timestamps and ids.
• templates/{video,social,slides}/README.md no longer say the logo is pending or that nothing renders.
• favicon-16/32/48.png and apple-touch-icon-180.png are regenerated (new hashes in the catalogue).

Deprecated

• The removal of the deprecated ui.font.fluid.*, ui.font.weight.bold and ui.motion.duration.{fast,base,slow} that 0.3.0 announced for 0.4.0 is postponed to 0.5.0: @okrado/ui still reads them.

[0.3.0] - 2026-10-31

Design language v1 and The Record mark (ADR-0076 in okrado/knowledge; spec in docs/reference/LANGUAGE.md).

Added

• Roles ui.primary.{solid,hover,on} (the ink primary action), ui.record.{solid,logo,text,subtle} (the record), ui.chart.now; core color.record.{ui,logo} (#c47500, #e48a00) and shadow.e2-dark.
• Type: ui.font.weight.display (540), ui.font.width.{display,heading} (108, 104) and the fluid marketing scale ui.font.marketing.{size,line-height,tracking}.{display,h2,h3,h4,lead,body,small,caption,mono}; Tailwind text-display … text-mono with line height and letter spacing.
• Layout and rhythm: ui.space.{0-5,32,42,section,hero-top}, ui.layout.{columns,margin,header,sidebar,inspector}, ui.radius.2xl; motion ui.motion.duration.{micro,standard,panel,write}, ui.motion.ease.panel.
• The Record logo system: logos/okrado/ and logos/studio/ generated by build/logo.py (npm run logos, --check in the tests) from geometry, the colour tokens and logos/source/wordmark.json; PNG renders; 34 catalogue entries. dist/web/logos/, dist/web/icons/ (favicons, touch and app icons), dist/web/og/ (OG 1200×630 and square 1080 templates plus renders, light and dark) and dist/web/construction.html; exports ./web/logos/*, ./web/icons/*, ./web/og/*, ./web/construction.html. Port brand.logo.
• brand.yaml language (principles, motif, doc) and logo (construction, clear space, minimum sizes, misuse, trademark caveat), both in dist/agent/brand.agent.json.

Changed

• Primary buttons are ink; ui.accent.* is the single commit action. Chart series are ink, blue, green, violet, teal, rose (amber is never a series).
• color.neutral.10 (ui.text.tertiary) #6b6f76 → #63676e: 4.40 → 4.95:1 on ui.bg.hover, now a text pair.
• ui.layout.content-max 1200 → 1280 px; ui.radius.lg 12 → 10, ui.radius.xl 16 → 14; ui.focus.offset 2 → 3; ui.font.tracking.display -0.02em → -0.04em; ui.motion.ease.standard → cubic-bezier(0.2, 0, 0, 1); ui.motion.duration.loop 1200 → 1600 ms; ui.shadow.e1 is a hairline plus a 12/32 drop; dark has no e1 and e2 = 0 24px 48px -16px rgba(0,0,0,.6).
• brand.yaml type.display is Archivo (540/108); video keeps Archivo Black (type.video).

Deprecated

• ui.font.fluid.* (use ui.font.marketing.size.*), ui.font.weight.bold, ui.motion.duration.{fast,base,slow} (aliases of micro, standard, panel). Removed in 0.4.0.

[0.2.1] - 2026-10-30

Added

• Published as @okrado/brand on GitHub Packages (publishConfig, files: [dist], release.yml from a v* tag with the job token), so consumers install it instead of vendoring dist/ (okrado/standard STANDARD.md §9). New export ./catalog.ndjson.

Changed

• CI pins the shared workflows of okrado/.github-private#9 and grants packages: read.

[0.2.0] - 2026-10-29

Added

• Web UI token layer (ADR-0060, colours, type and scale of ADR-0070, all status: proposed): OKLCH ramps for neutral, amber, blue, green, orange and red (12 steps, light and dark, hex fallback), data-viz hues, scrim and elevation in the ui-core set; semantic ui.* roles with mode (light, dark) and density (comfortable, compact) modifiers; UI type, 4 px spacing, radius, focus, 24/44 px hit area and motion tokens with reduced-motion values.
• dist/web/: ui.css (:root, [data-mode], prefers-color-scheme, [data-density], pointer: coarse, prefers-reduced-motion), brands/<id>.css (overrides only), tailwind/theme.css (Tailwind v4 @theme inline, semantic names only, defaults reset), tokens.json + tokens.d.ts, and a self-contained specimen.html.
• UI contrast gate: 60 pairs in brand.yaml → color.ui.contrast checked in every brand × mode (text 4.5:1, large text and non-text 3:1), no known failures; a fixture tenant with a bad pair proves it refuses.
• brand.ui port in okrado.component.yaml; package exports ./web/*; Archivo variable, Inter and JetBrains Mono Fontsource packages in fonts/manifest.yaml (web), with Archivo’s OFL text.

Changed

• tokens/resolver.json names the items each output uses ($extensions.com.okrado.outputs); the video outputs are unchanged apart from the version in their headers.
• A font name that is already quoted is no longer quoted twice through an alias.

[0.1.0] - untagged

Added

• DTCG 2025.10 tokens (core, semantic themes, formats, motion), the brand spec, the fonts manifest and the asset catalogue with licences and consent.
• The Style Dictionary 5 build: CSS, TS, the Studio brand.json, the Remotion theme and the agent JSON.
• Tests for DTCG validity, the build snapshot, Studio parity and contrast; the applying-brand skill.
• okrado.component.yaml declaring brand.kit and brand.assets; provenance required on AI-generated assets and a promotion checklist for Studio-generated assets.

Changed

• Biome no longer formats Markdown (Okrado Standard, @okrado/config).
• CI calls the shared gates-node.yml and secret-scan.yml from okrado/.github-private v0.2.1, pinned by commit SHA (was tag-pinned actions/*@v4); npm run gates:ci adds the dist/ drift check. TypeScript 7.0.2 (ADR-0037). tests/toolchain.test.ts guards both.