Version authority, changelog, sources

Provenance

Where every number came from, when it was read, and which reads are still outstanding. This system has been wrong before — nine token values were wrong at authorship, a motion block was closed on a false claim, and an entire spacing scale was invented. Each of those is recorded here rather than quietly fixed, because a correction nobody can see is indistinguishable from the error.

Version authority

README.md in the source repository is the version authority. The Claude Design project that mirrors this folder is titled "SWAGTRON SHOPIFY DESIGN SYSTEM · v0.3.0". Its contents are v0.4.0 as of 2026-08-29; its title still says v0.3.0. There is no rename API — a Claude Design project's title is fixed at creation — so the title cannot be corrected in place and this note is the correction. If the two ever disagree, the README wins. The project title is not an authority on anything.

WhatVersionPinned by
This design systemv0.4.0README.md, 2026-08-29
The theme it documentsConcept v6.0.1config/settings_schema.json → theme_info, read 2026-08-29 by LAR-1415 (C-0d)
The live theme#160946684156RT-C-V2 — Site Wide & Product Page Fixes.
Theme authorRoarThemeDocumentation index at roartheme.co/blogs/concept

C-0d: every dated read before 2026-08-29 was made against v6.0.0 and is flagged rather than restated as current. Re-verify any value quoted from a v6.0.0-era read. The settings-backed tokens were re-read against the installed Concept v6.0.1 on 2026-08-30: 44 tokens traceable to a key in the live config/settings_data.json, all unchanged, zero drift. The long-quoted count of 38 was an undercount and was never enumerated. --radius-badge has no settings key and is a repo-side alias of --radius-button. The enum-to-value mapping in snippets/css-variables.liquid has not been re-read against v6.0.1.

Changelog

v0.4.0 Full theme ingest

2026-08-29 · Paperclip LAR-1415, applied by LAR-1430

LAR-1415 read the installed Concept theme file by file and found the inventory incomplete: 208 native items missing. The theme ships five layers and we had ingested one. The section layer alone would have read as COMPLETE (101 found, 101 recorded); the gap was entirely in blocks, snippets, JS elements and keyframes.

v0.3.0 and earlier

Not recorded as a changelog at the time

The material history is in the provenance sections below and in the git log.

IssueWhat it settled
LAR-869Section provenance. main-article-banner and main-article-overlay are stock Concept sections, not SWAGTRON customizations. In the theme editor they are labelled "Blog post banner" and "Blog post" — the filenames are never shown to merchants.
LAR-870Token provenance corrected. The previous claim that all tokens were ground truth extracted from settings_data.json was false for nine of them.
LAR-875Motion resolved. assets/theme.css had been skipped rather than searched.
LAR-876Four UNVERIFIED entries closed; three phantom tokens deleted with tombstones. Established the no-vertical-lift law across all 354 theme files.
LAR-958Deploy pipeline. Push to main redeploys production; there is no build step.
LAR-977--space-* retired for the theme's real --sp-* scale; editorial register; email adopted as the fourth surface.

Token provenance is not uniform

Corrected 2026-07-29 (LAR-870). The distinction matters, and the previous wording on this page claimed all tokens were ground truth extracted from settings_data.json — that was false for nine of them.

Settings-backed — ground truth

Colour, typography, spacing and the settings-backed shape values were extracted from the live swagtron.com store's config/settings_data.json on 2026-07-13 and re-verified on 2026-07-29. Both of those reads were v6.0.0-era — see C-0d. The settings-backed tokens were re-read against the installed Concept v6.0.1 on 2026-08-30: 44 tokens traceable to a key in the live config/settings_data.json, all unchanged, zero drift. The long-quoted count of 38 was an undercount and was never enumerated. --radius-badge has no settings key and is a repo-side alias of --radius-button. The enum-to-value mapping in snippets/css-variables.liquid has not been re-read against v6.0.1.

Theme-CSS-derived — nine were wrong at authorship

Shape, elevation, input, button and card values were derived from assets/theme.css and snippets/css-variables.liquid, not from settings. Nine did not match the live theme and never had. Corrected 2026-07-29. Three were visible design errors:

The root cause is now known: the token sheet was derived from theme.css and css-variables.liquid without the six section-*-style snippets, which are the single source of truth for how every section's padding, gap, border, overlay and size settings become CSS.

Formerly UNVERIFIED — five entries, now all resolved

The motion block, --container-narrow, --shadow-card-hover, and the .card:hover and .button:active lifts.

Spacing — the invented scale was retired 2026-08-10 (LAR-977)

tokens.css previously carried a 13-entry --space-* scale (0/4/8/…/120px). It was invented at authorship — a reading of the theme's section-padding slider, not the theme's spacing closure. Deleted with a tombstone and replaced by the theme's real 46-entry --sp-* scale. Do not reintroduce --space-*.

Three --sp-* values are irregular and flagged inline: --sp-15 is 62px (not 60), --sp-23 is 90px, and --sp-100 is 512px, which breaks the name/value relationship entirely. Never infer an --sp-* value from its name — read it.

Motion — resolved 2026-07-28, corrected 2026-08-29

The theme's motion vocabulary was never missing; assets/theme.css had been skipped rather than searched, because at 349,322 bytes it does not fit in a document read. The Shopify Admin API returns a signed body URL (OnlineStoreThemeFileBodyUrl) for files that large. Fetched and searched, --animation-primary resolves to 0.5s cubic-bezier(0.3, 1, 0.3, 1) across 74 call sites.

The earlier claim that "the motion values were read from the live theme's own CSS custom properties" was false, and the correction stands. The theme's own custom properties are a different vocabulary. Both vocabularies are now recorded, and the divergence between them is deliberate: the durations agree (200 / 300 / 500ms), the easings do not.

Four values remain ours with no theme counterpart — --duration-slow, --duration-extended, --cubic-out, --duration-marquee — and must not be described as read from the store.

On 2026-08-29, LAR-1415 established that closing where the theme keeps its motion vocabulary had not closed what the theme actually runs. Four of the values that block carried were wrong. See Motion.

The four surfaces

Three surfaces are represented in the built system as UI kits: the Storefront (dot-com), SWAG MAG (the blog index, dot-com), and a Campaign creator-giveaway landing page. A fourth surface, marketing email, is represented as a template rather than a UI kit.

Email is the one surface that cannot resolve the token layer. It is sent from Klaviyo as custom-coded HTML recompiled through MJML before send. It shares the token set unchanged and adds no colours, but the canvas is different — 600px single column, no JS, no hover, and inline literal values, because no email client resolves var(). That makes email the only place where a token value is transcribed rather than referenced, and therefore the only place where a stale token silently survives a token correction. Re-check email literals against tokens.css after any token change. See Campaign.

Content rules

NEVER INVENT CONTENT. Rule added 2026-07-30, merged 2026-08-10 (LAR-977). No invented event names, dates, venues, stats, prices, or claims — anywhere, ever. Where the real value is unknown, render a clearly labelled [PLACEHOLDER — what goes here] instead. This has the same standing as the buildability constraint: it is a hard constraint, not a preference. The purge that installed the rule removed an invented "Demo Days · Pasadena · August 12" event and reconciled every price and spec in the built system against the live-verified catalog.

Product specs and prices are not owned by this design system. They are owned by the SWAGTRON project canon, and this folder deliberately does not restate them. Verify against product-specs-canonical.md (specs) and pricing-sku-canonical.md (prices). Those files win every conflict, including against anything cached in the built design system. Restating a figure here would create a fourth copy to drift — the pointer is the deliverable.

FigureStatus
60+ miles rangeGate-checked against vault canon 2026-08-10 — agrees
28 MPH Class 3Gate-checked 2026-08-10 — agrees
48V 15.6Ah (≈749 Wh)Gate-checked 2026-08-10 — agrees
UrbanCruise priceDid not clear cleanly. product-specs-canonical.md carries $1,499 and delegates pricing to pricing-sku-canonical.md, which records $1,499.99 from a 2026-07-31 live cart check. Use pricing-sku-canonical.md and re-check before publishing — it is the figure that has moved most recently.
Helmet, lock, rack, fendersUnverified sample data. Must not be treated as catalog truth.

Sources and links

What is in the source folder

FileWhat it is
DESIGN.mdThe written system definition — purpose, brand, voices, structure, motion, accessibility, conventions. Read this first.
tokens.cssThe canonical tokens as CSS custom properties, plus the non-negotiable component rules. The numeric source layer.
components/native-motion-inventory.mdNew in v0.4.0. The stock Concept components we own but had never written down.
reference/theme-full-inventory-2026-08-29.mdNew in v0.4.0. The authoritative census. Wins over any theme total stated elsewhere.
concept-theme-capabilities.mdThe capability catalogue — the outer edge of what the theme can build. Written against v6.0.0 and not re-read against v6.0.1.
guidelines/email-mapping.mdThe marketing-email section map — canvas rules, module-to-section mapping, pre-send checks.
tokens/rules.cssThe same component rules in the built system's .swag-* namespaced form. Reference, not a second source — and it does not carry the reduced-motion block.
design-readme-ec7c4306.mdRead-only reference: the built system's own readme, verbatim. Describes the built system, not this folder. Not authoritative here.

The two retired specimens

RETIRED as authorities — 2026-07-29. the token sheet and Batch 1 were previously ranked #1 and #3 in the authority list. They are no longer authorities on anything numeric. They are frozen snapshots of a superseded state, and their staleness was verified by grep rather than assumed — Batch 1 carries 9999px ×14, 0 4px 16px ×6, outline:3px ×1; the token sheet carries 9999px ×6, 0 4px 16px ×2, outline:3px ×4, plus a fixed type scale.

They are kept as historical reference for composition, density and register only — the register work in them is still good and was never the problem. They are deliberately not being re-rendered. Re-rendering resets the clock without fixing the failure class: any frozen render drifts the moment a token moves. Their in-system equivalents already render from tokens, so they cannot drift the same way. That is the durable fix, and it is already done.

The token sheet's header comment says its values were "Extracted from the LIVE swagtron.com Concept v6.0.0 settings_data.json". That line is correct as written and is deliberately left alone — the extraction really was v6.0.0-era (2026-07-13, re-verified 2026-07-29). Rewriting it to v6.0.1 would falsify a true provenance statement. C-0d is the note that the read is now stale, not that it was mislabelled.

CANNOT-VERIFY register

Open items. Each is a claim this system cannot currently support with a tool. Entries that have since been discharged are marked DISCHARGED and kept in place — the register is the history, so nothing is deleted from it.

DISCHARGED 2026-08-30 — was: CANNOT-VERIFY that the settings-backed tokens still hold under v6.0.1. Retained rather than deleted, because the register is the history. The settings-backed tokens were re-read against the installed Concept v6.0.1 on 2026-08-30: 44 tokens traceable to a key in the live config/settings_data.json, all unchanged, zero drift. The long-quoted count of 38 was an undercount and was never enumerated. --radius-badge has no settings key and is a repo-side alias of --radius-button. The enum-to-value mapping in snippets/css-variables.liquid has not been re-read against v6.0.1 — that part of C-0d stays open.

CANNOT-VERIFY: that the live theme RT-C-V2 is byte-identical to a pristine Roar Concept v6.0.1 download. RT-C-V2 is the SWAGTRON working theme and carries at least one confirmed local modification (swagmag-editorial.css). Every enumeration is "what is installed", which is what was asked for as ground truth.

CANNOT-VERIFY: which specific 14 enumerated items are the relisted overlap between the 222 names listed in the census and the 208 set-difference.

CANNOT-VERIFY: which decomposition of Addendum C yields LAR-1415's headline "24". Cite "21 register entries covering 29 distinct native items" instead.

CANNOT-VERIFY: that the 21 native-motion entries render correctly under the SWAGTRON settings_data.json without a build. Candidacy is asserted from schema and JS behaviour, not from a rendered page.

CANNOT-VERIFY: whether the creator roster is 7 or 8. Two sources dated the same day disagree. See Campaign. Unblock owner: the operator / campaign owner.

CANNOT-VERIFY: the scope of campaign Addenda D, E and F. No completion comment on LAR-1409 / 1415 / 1423 / 1427 / 1437 names them.

CANNOT-VERIFY: that concept-theme-capabilities.md holds under v6.0.1. It was written against v6.0.0 and has not been re-read.