THE WORD FOR ALL THE WORLD · System Review

The standard is finished. The toolkit is not.

A review of brand.theword.world against what a designer, an engineer, an ad buyer, and a volunteer each need from it.

The verdict

The architecture is right and the discipline is unusually good. What is missing is not heavier machinery, it is output: the system states the law beautifully and hands you almost nothing to build with.

Static HTML is the correct choice and should stay. The work ahead is to emit more artifacts from the same source, not to replace the source with a framework. Every gap below is additive: nothing already built needs to be undone.

Is HTML enough
YesKeep it. The durability is the product. Add output targets, not a runtime.
Figma
Yes, generatedOne way, repo to Figma. Never a source of truth.
Canva
Yes, urgentlyTwo ungoverned kits exist today. This is the live drift.
Storybook
NoA generated component gallery instead. Same benefit, no build chain.
01 · The baseline

What already works, and must not be traded away.

Most brand portals are a PDF and a Dropbox link. This one has properties that are rare enough to name, because the recommendations that follow are only safe if these survive them.

02 · Diagnosis

Two findings explain every gap in this report.

Finding one Structural

It is a complete constitution and an incomplete toolkit.

The system answers what is true and what is forbidden with real authority. It does not yet answer give me the thing. A designer opening it to build a Google Ad gets six laws and six hex values. A developer starting a second website gets a palette and retypes every button by hand. A volunteer opening Canva gets a kit this repository has never heard of.

The distance between the standard and the artifact is where drift is born, and right now that whole distance is covered by human judgment and goodwill. Every layer that closes it converts a judgment call into a default.

A rule that has to be remembered is a rule that will be broken. A rule that ships as a file is a rule that holds.

Concretely: tokens.json stops at color and type family. There is no spacing scale, no named type scale, no elevation, no motion, no neutral ramp, no print color space. components.json describes thirteen components in prose and ships CSS for none of them, so the only way to reproduce a card is to read the portal's inline stylesheet. And no file anywhere states what a 1080 by 1350 post, a 600 pixel email, a responsive search ad, or a 300 dpi tri-fold is supposed to be.

Finding two Refactor, not urgent

The guide is the database.

brandsource.py recovers structured facts by running twenty-odd regular expressions over brand/index.html: the :root block, the token table rows, the proportion heading, the changelog. It works, it fails loudly, and it has held. But the direction of authority is inverted. The presentation layer owns the data.

Three consequences, in increasing order of cost. A designer cannot propose a color change without editing a hundred-kilobyte HTML file. Any visual redesign of the guide is a breaking change to the build. And a fact with no natural visual home has nowhere to live, which is exactly why ai-source/ exists as a second parallel truth alongside the first.

The fix is to invert it: a structured token source generates the guide's :root and its color and token tables, and the guide keeps owning prose, which genuinely does belong in markup. Do this last, after the value is proven, or skip it if phases one through five land cleanly.

03 · The question you asked

Is plain HTML enough, or does this need heavier machinery?

Keep the HTML. This is not a compromise answer, it is the correct one, for three reasons.

One real gap in the current setup, and it sits directly under the future you described. The GitHub Action verifies pull requests but only deploys on main, so a designer's PR produces a pass or a fail and no way to look at what changed. For "designers open PRs against the standard" to be real, a PR needs a preview URL and a visual diff. That is a short afternoon of work and it is the biggest gain for its size in this report.

04 · Design audit

The visual system, judged as an interface system.

As a brand language it is strong: six colors, three faces, three radii, a 60 / 30 / 10 proportion, and a genuinely distinctive law that fire never carries text. Tight systems produce consistency, and the restraint here is an asset. Do not loosen it.

Judged as the foundation for apps, dashboards, forms, and email, four specific things are missing. Each one has a predictable failure: somebody improvises, and the improvisation is invisible until it is everywhere.

GapWhat exists nowWhat happens without itSeverity
No neutral ramp Midnight, Parchment, White, plus two one-off rgba rules Disabled states, dividers, input fills, table stripes, and skeletons each get an improvised rgba(). B1 of your own audit fails on your own future work. High
No error or warning color Success only, #5FAD56, forms and dashboards The first developer who needs an error state reaches for Flame. Flame carrying text is gate G4, an automatic audit failure. This violation is close to certain. High
One breakpoint 720px, single column below Email needs 600. Wide dashboards and tables need roughly 1080. Both get invented per project. Medium
No dark UI theme Midnight as a design ground, which is a different thing An app or an email in dark mode has no token mapping. Gmail's dark-mode inversion will recolor Ember and nobody has decided what it becomes. Medium
No print color space "Never send a PNG to a printer" and the hex values The printer asks for CMYK or Pantone, someone converts on the spot with an unknown profile, and Ember comes back muddy on a banner nobody can reprint. High
Radius and measure live in prose "3px buttons · 4px cards · 6px frames" as a sentence Real values that cannot be consumed by a stylesheet, a Figma variable, or a Tailwind config. Medium

The right fix for the neutral ramp keeps the system tight: define it as tints and shades of Midnight and Parchment rather than adding grey. Five steps, named, derived. It stays unmistakably yours and it stops being improvised. Same principle for error and warning: derive them so they read as part of this palette rather than borrowed from a UI kit, and record explicitly that neither may be Flame.

05 · Coverage

Every channel you named, and what it would find today.

This is the concrete form of finding one. Read the right column as the list of decisions currently being made by whoever happens to be doing the work.

SurfaceCoveredMissingState
The brand portal itselfEverything, and beautifullyNothingComplete
Any other websiteSix laws, palette, type rules, thirteen component descriptionsNo brand.css to link and no installable token package. No spacing or type scale. No component CSS. Every build, React or otherwise, re-derives the system by eye.Gap
App, web or nativeColors and typeDark theme mapping, app icon spec, 44px touch minimum, state tokens beyond hover and focus, elevation, empty and loading states.Gap
Google Ads, search and RSABanned words, voice, tone filterNo headline or description bank written to the 30 and 90 character limits. No sitelink, callout, or structured snippet copy. No display path rules.Gap
Google Ads, display and PMaxLogo files in every formatNo asset set at the required 1.91:1, 1:1, and 4:5 ratios. No safe-area rules for auto-cropped placements. No Performance Max asset checklist.Gap
Email and newsletter"Use a 400 or 800px PNG, most clients block SVG"No 600px table-based template. No email-safe fallback tokens. No dark-mode inversion decision. No preheader, footer, or unsubscribe standard.Gap
PrintSend the vector, never a PNGNo CMYK or Pantone values. No bleed, margin, or minimum millimetre sizes. No paper stock note. A printer will ask for all of these.Gap
Social, organicHandles per platform, glyph for avatarsNo canvas sizes, no title-safe zones for stories and reels, no caption or CTA templates.Partial
VideoLower third, subtitles, scrim law, 6 to 15 second loopsNo export presets, no title-safe area, no end card or bumper, no grading note.Partial
Presentations and decksThe word "deck" appears twice in the standardNo master template. templates/ contains one empty .gitkeep.Gap
Merch, signage, vehiclesThe one-color -black.svg route for embroidery and engraving, which is genuinely goodGarment color rules, minimum physical sizes, vehicle and banner specs.Partial
Social preview cardsFavicon files exist in assets/No og:image on any page, no favicon spec in the guide, no per-page card. Every share of a brand URL renders blank.Partial
06 · Tools

Canva, Figma, Storybook: three different answers.

Canva Do this first

Yes, and this is your only live drift right now.

Your Canva account currently holds two brand kits: "THE WORD Branding Kit" and "THE WORD FOR ALL THE WORLD". Neither is governed by this repository, neither carries a version, and nothing anywhere can tell you which one a volunteer used last Tuesday.

Canva matters more than Figma here, because Canva is where the people who are not designers actually make things: the flyer for a city gathering, the certificate, the conference recap post. That is where a brand actually breaks, and it is the one surface this system currently cannot see.

Do: consolidate to one kit. Stamp the version into its name, so THE WORD · v6.8 is visible to everyone who opens it. Load exactly the six colors and three families, no extras. Build locked Brand Templates for the five recurring jobs rather than leaving people on a blank canvas. Then register the kit id in the repository with the version it was last synced to, so the linter can say out loud that Canva is running v6.6 while the standard is v6.8. Push what the Connect API supports and print a short manual checklist for the rest.

Figma

Yes, generated one way, never a source.

This is exactly the loop you described: a designer proposes a change as a pull request against the token source, it is reviewed and merged, and an action pushes the new values into Figma Variables through the REST API. Their library updates. Nobody retypes a hex.

The library file carries Variables for color, type, and spacing, Text Styles, Effect Styles, and components whose names match components.json ids exactly, so a Figma layer and an audit finding refer to the same thing. Register the file key alongside the Canva kit with its synced version.

The rule that makes it work: Figma is a consumer, never an origin. The moment someone changes a variable in Figma instead of in the repository, you have two standards again, and the one with the nicer interface always wins.

Storybook

Not in this repository. In your product repositories, yes.

These are two different jobs and the answer differs for each. In the brand repository, Storybook means Node, a component framework, a bundler, and a dependency tree that needs maintaining, all to document HTML snippets. That contradicts the property that makes this system good, and it buys one thing you actually want: a page where every component renders live next to its spec.

Generate that page instead. /components/, built by build_ai.py from components.json, rendering each component with its spec, its copyable HTML, its do and don't, and its appearance on both grounds. Zero new dependencies, correct by the same mechanism as everything else here.

In a Next.js product repository, Storybook is a reasonable and probably good choice. It documents your React components, which is not what the brand repository publishes. Name each story after the component id in components.json, so a story, a Figma layer, and an audit finding all refer to the same thing by the same name.

Next.js Changes the plan

Building real apps moves one thing forward and adds one rule.

The plan below was written assuming this repository was the only codebase. If you are building Next.js sites and apps, the architecture holds unchanged, but the package that phase one treats as optional becomes the main delivery mechanism, and it should ship in phase one rather than later.

What changes. A React application does not consume brand.css, it consumes tokens and builds its own components against them. So publish @theword/brand as an installable package carrying the tokens as CSS custom properties, as typed TypeScript exports, and as a Tailwind preset. Then a brand version bump opens a dependency pull request in every application repository automatically. That is the mechanism that makes "a designer changes the standard and everything updates" reach the apps, rather than stopping at the portal.

What stays. brand.css is still worth building, because the majority case is not a Next.js app. It is a landing page, a partner microsite, an email, a page someone builds in an afternoon. Both artifacts come from the same token source, so they cannot disagree.

Two small Next.js specifics. Load the three faces with next/font/google rather than a stylesheet link: it self-hosts at build time, which removes the third-party request and the layout shift, and it matches the self-hosting already recommended in phase zero. And keep theming in CSS custom properties rather than a JavaScript theme object, so it works unchanged in server components.

Reuse Read this one

The gallery is a reference. It is not a distribution channel.

Worth being explicit, because it is the assumption most likely to cost you a rebuild. You cannot import a card out of the HTML gallery into a Next.js app. What travels between them is the token layer and the specification, not the markup.

A React Card in an initiative app looks identical to the Card in the gallery because both read the same variables, spacing, radii, and states from the same source. But the React version is written once, by hand, in a library that every initiative app installs. That library is the thing that travels, and it is worth building precisely because you have more than one app.

Three artifacts, three jobs, one source underneath all of them.

ArtifactWhat it isWho uses it
@theword/brand Tokens only. CSS custom properties, typed exports, Tailwind preset. No components. Everything. Every app, every site, and the gallery itself.
/components/ The canonical rendering, with copyable HTML and CSS beside each spec. Nobody installs it. Landing pages, emails, partner microsites, and anyone working outside React copy from it.
@theword/ui The React implementation of those same specs. Storybook lives here and documents this. The initiative applications.

Why not collapse this into one React library. An email cannot consume React, and neither can a static microsite or a partner's own CMS. If the only real components live in React, the brand forks the first time someone builds outside Next.js, and it forks quietly. Tokens sitting underneath both implementations is what prevents that.

Neither implementation is the source. components.json is. The gallery and the React library are both consumers of it, registered with the version they were built against, exactly like Figma and Canva. One id names each component in the gallery, in its Storybook story, in its Figma layer, and in an audit finding, so a Card is a Card everywhere anyone looks it up.

07 · Execution

The plan, in the order it should be done.

Sequential, because each phase depends on the one before it. Every phase carries an acceptance test, so "done" is a fact rather than an opinion. Each of these can be handed back as a single instruction.

00Fragilities

Close the small things first.

None of these are hard. All of them are promises the repository currently makes and does not keep.

TaskWhere
Enable Cloudflare Pages preview deploys on pull requests and comment the URL on the PR.github/workflows/
Fill or delete templates/ and assets/fonts/. Two empty directories promising thingstemplates/, assets/fonts/
Self-host DM Serif and DM Sans locally under OFL, keep the Google Fonts link as the documented alternativeassets/fonts/
Add og:image, og:title, and a favicon spec to every page, and lint for their presenceall pages, brand_lint.py
Compute contrast ratios over every declared foreground and background pair and assert WCAG AA in CIbrand_lint.py
AcceptanceOpening a pull request produces a preview URL. The portal renders correctly with fonts.googleapis.com blocked. Changing Ember to a value that fails AA fails the build.
01Tokens

Finish the token layer, then emit it everywhere.

The phase that pays for the most. Everything after it is cheap once this exists, and nothing after it is possible without it.

TaskWhere
New hand-authored source adding: spacing scale, named type scale with line heights, radius as tokens, neutral ramp derived from Midnight and Parchment, error and warning derived in-palette, elevation, motion duration and easing, three breakpoints, opacity, z-index, touch target minimumai-source/tokens.json
Print color: CMYK, Pantone, and RGB for all six, with the conversion profile recorded beside themsame
Email-safe fallbacks per token: literal hex only, Georgia and Arial stacks, and a recorded decision on dark-mode inversionsame
Emit from that one source: ai/tokens.json unchanged for compatibility, ai/tokens.dtcg.json in W3C Design Tokens format, assets/brand.css, ai/tokens.ts, ai/tailwind.preset.js, and an .ase swatch file in the download packstools/build_ai.py
Publish the tokens as an installable package so application repositories get a dependency pull request on every version bump@theword/brand
Point the portal's own pages at assets/brand.css instead of inline copiesall pages
AcceptanceThe portal renders from the same CSS file it publishes to everyone else. That is the proof: if it is good enough for you, it is good enough to hand out.
02Components

Make the components usable, not just described.

TaskWhere
Give every entry real CSS and real HTML. Roughly half currently have no html field at allai-source/components.json
Add the components the other channels need: email button as a table, ad headline and description, social post frame, certificate, lower third, end card, letterhead block, business card, form field with its error statesame
Generate a live /components/ gallery: rendered component, spec, copyable HTML, do and don't, both groundstools/build_ai.py
Publish the React implementation, one component per components.json id, with Storybook in that repository and stories named after those same ids@theword/ui
AcceptanceA developer building a second website links one stylesheet and retypes nothing out of the guide. A developer building an initiative app installs two packages and implements no component twice.
03Channels

Add the layer that answers "how do I make a Google Ad".

This is the phase that turns the portal from a brand guide into the thing you described at the start: somewhere every discipline can go and leave with what it needs.

TaskWhere
One entry per surface: canvas sizes, safe areas, required assets, character limits, file formats, color space, do and don't, and which audit checks applyai-source/channels.json
Generate the human pages: web, app, email, ads, print, social, video, presentations/channels/*
A copy bank of pre-approved strings: RSA headlines at 30 characters, descriptions at 90, subject lines, preheaders, CTAs, boilerplate in three lengths, tagline variants. Each one audited once, then reusable foreverai-source/copy-bank.json
AcceptanceSomeone told to build a search campaign can assemble every headline, description, extension, and image from /ai/channels.json and /ai/copy-bank.json without making a single judgment call.
04Consumers

Make every downstream surface visible and syncable.

TaskWhere
A registry of every surface running this brand: Canva kit ids, Figma file key, the React component library, each website, each app, the email platform. Each with the version it was last synced toai-source/consumers.json
Push variables and styles into Figma from the token source on releasetools/sync_figma.py
Consolidate to one Canva kit, stamp the version into its name, push what the API allows, print a checklist for the resttools/sync_canva.py
Warn on any consumer whose synced version trails the current onetools/brand_lint.py
AcceptanceRunning the linter names every surface in the organization that is running an old version of the brand, by name and by version.
05Enforcement

Make the standard checkable outside this repository.

Roughly half your audit is mechanically decidable: unknown hexes, non-brand fonts, text on Flame, contrast failures, banned words, a missing endorsement line. The linter already proves these about the portal. It cannot yet be pointed at anyone else's work.

TaskWhere
A checker that takes a file path or a URL and runs the mechanical half of the audit against it, returning the standard report shapetools/brand_check.py
Publish it as a GitHub Action any other repository can add in three lines, alongside the existing loader skillskills/, action manifest
AcceptanceAnother repository's CI fails when someone commits an off-brand hex, and the failure message cites the brand version it was measured against.
06Optional

Invert the source, or decide you never needed to.

Finding two, addressed. The structured token source generates the guide's :root block and its color and token tables, instead of the build regex-parsing them back out of rendered markup. The guides keep owning prose, rules, and do and don'ts, which is what markup is genuinely for.

Do this only after phases one through five have proven their value. If they land cleanly and nobody is fighting the HTML, this is a refactor you can honestly skip.

AcceptanceChanging a brand color is a one-line diff in a data file, and the guide, the AI layer, the CSS, the Figma library, and the Canva kit all follow from it without a second edit.
08 · Guardrails

What not to do, however reasonable it sounds.

Each of these will be proposed by someone competent at some point. The reason to write them down now is that the argument for each is genuinely persuasive in the moment.

09 · If you do nothing else

Three things close most of the real drift.

01

Consolidate Canva

One kit, version in the name, registered in the repository. This is the only drift happening right now rather than hypothetically, and it is a single afternoon.

02

Ship brand.css

Finish the tokens, emit a real stylesheet, and make the portal itself consume it. Every future website, app, and email stops re-deriving the system by eye.

03

Add the channel layer

Channels plus a copy bank. This is what turns a brand guide into somewhere an ad buyer, a printer, and a newsletter editor can each go and leave with the answer.

Everything else in this report is worth doing and none of it is urgent. The architecture underneath is sound, the discipline is real, and the gap is additive. That is a good position to be in.