@codecavepro/brand 1.5.0 → 1.6.0

package/README.md

@@ -45,7 +45,7 @@ redesign turns into a find-and-replace across your codebase.
 
 ### Already have your own base styles? Import the values only
 
-`@codecavepro/brand/css` is the design system **whole**: the tokens, six `@font-face`
+`@codecavepro/brand/css` is the design system **whole**: the tokens, ten `@font-face`
 rules, base rules for `html`, `body`, `h1`–`h6` and `a`, two layout primitives and
 around sixty component classes. That is what you want for a page that should look like
 CODECAVE. It is *not* what you want in an app that already has a base layer — dropping
@@ -78,7 +78,7 @@ file at that URL are provably the same bytes.
 
 ## Fonts: this package ships none
 
-`@codecavepro/brand/css` declares six `@font-face` rules for **Satoshi**, but **no font
+`@codecavepro/brand/css` declares ten `@font-face` rules for **Satoshi**, but **no font
 binaries are included** — that is a licensing question, not an oversight. Until you
 supply the files, the faces 404 and the browser falls back down the stack
 (`-apple-system`, `Segoe UI`, Roboto, …). Tokens, colours and the type *scale* are all
@@ -93,10 +93,17 @@ dropped into a project on its own:
 | `@codecavepro/brand/fonts.css` | `./Satoshi-*.woff2` | **beside** the stylesheet itself |
 | `@codecavepro/brand/tokens.css` | *none — it declares no faces* | wherever your own `@font-face` rules point |
 
-Get the cuts from [Fontshare](https://www.fontshare.com/fonts/satoshi) — Light 300,
-Regular 400, Italic, Medium 500, Bold 700, Black 900. Bind each with a real
-`font-weight` descriptor rather than letting the browser synthesize; the design system
-documents why in [DESIGN.md §10.3](https://github.com/CodeCavePro/brand/blob/development/docs/DESIGN.md#103-synthesized-vs-real-font-weights).
+Get the cuts from [Fontshare](https://www.fontshare.com/fonts/satoshi) — 300, 400, 500,
+700 and 900, each upright and italic, which is the ten faces these stylesheets declare.
+Bind each with a real `font-weight` descriptor rather than letting the browser
+synthesize; the design system documents why in
+[DESIGN.md §10.3](https://github.com/CodeCavePro/brand/blob/development/docs/DESIGN.md#103-synthesized-vs-real-font-weights).
+
+**Do not use the `stylesheet.css` that comes in the Fontshare download.** It declares
+Bold and Black *both* as `font-weight: bold`, and their italics likewise, so four cuts
+collide into two slots and whichever is declared last silently wins — your `900` text
+renders Bold, or your `700` renders Black, with nothing to indicate which. Take the
+binaries from that download and the declarations from here.
 
 ## The typed module
 
@@ -186,15 +193,45 @@ you need both:
 @import "@codecavepro/brand/theme.css";
 ```
 
-**That order is load-bearing, and `tokens.css` must stay unlayered.** Several entries in
-`theme.css` are deliberate self-references (`--color-glow-25: var(--color-glow-25)`):
-the declaration is what makes Tailwind emit the utility, while the value comes from
-`tokens.css`, whose unlayered `:root` outranks `@layer theme`. Wrap `tokens.css` in a
-cascade layer — or leave it out — and those names resolve to nothing.
+**`tokens.css` must stay unlayered.** Several entries in `theme.css` are deliberate
+self-references (`--color-glow-25: var(--color-glow-25)`): the declaration is what makes
+Tailwind emit the utility, while the value comes from `tokens.css`, whose unlayered
+`:root` outranks `@layer theme`. Wrap `tokens.css` in a cascade layer — or leave it out —
+and those names resolve to nothing. Measured on codecave.pro: importing it as
+`layer(brand)` changes the emitted CSS and moves a stylesheet's content hash.
+
+The order of those two lines, by contrast, is convention rather than a constraint —
+Tailwind collects every `@theme` and `:root` in the stylesheet before it emits anything,
+so reversing them produced byte-identical output. They are written values-then-names
+because that is the direction of the dependency.
 
 Import only `tokens.css` and the components mount and behave correctly and render
 nearly unstyled.
 
+### Installing the components? Tailwind cannot see them
+
+**Tailwind's automatic content detection skips `node_modules`, and this package ships Vue
+source.** So a utility class used only inside a component you install exists nowhere
+Tailwind reads, and is simply never emitted. Add the package to the scan:
+
+```css
+@source "../../node_modules/@codecavepro/brand/dist/src";
+```
+
+Adjust the path to be relative to the stylesheet the `@source` sits in. It **adds** to the
+automatic scan rather than narrowing it.
+
+This is the failure mode to know about because nothing reports it: the build succeeds, a
+typecheck reports no errors, and the affected elements render unstyled. Leaving the line
+out while installing `Button.vue` alone cost codecave.pro 783 bytes of CSS and all 12 of
+the utilities only that component uses — every button on the site, silently.
+
+Because nothing reports it, it is worth checking rather than remembering. codecave.pro
+does it by asking Tailwind twice: its own scanner for the class names inside this
+package, its own compiler for which of those are real utilities, and then whether each
+one is in the CSS the build emitted. That reads the same answer Tailwind would, so it
+cannot go stale when this package gains a component.
+
 ### The content-shaped four resolve their own image URLs
 
 `ArticlePreview`, `Review`, `pain-points-item` and `technologies` render CMS content, so

package/dist/colors_and_type.css

@@ -19,12 +19,11 @@
 /* ---------------------------------------------------------------------------
  * Font faces
  *
- * PROVENANCE NOTE — this differs from production on purpose.
- * codecave.pro ships exactly ONE real cut (Satoshi-Regular.ttf, weight 400)
- * and lets the browser synthesize 300 and 700. This package ships the real
- * Satoshi cuts captured in the brand asset upload, so bound weights render
- * genuinely rather than faux-bolded. Designs built here will look very
- * slightly tighter at 700 than the live site does today.
+ * The ten faces are bound to explicit numeric weights in both styles. The
+ * vendor's own stylesheet.css declares Bold and Black as the same
+ * `font-weight: bold`, and their italics likewise, so four cuts collide into
+ * two slots there and the last one declared silently wins. That is the defect
+ * these declarations exist to avoid; do not replace them with the vendor file.
  * ------------------------------------------------------------------------ */
 
 @font-face {
@@ -36,6 +35,15 @@
   font-display: swap;
 }
 
+@font-face {
+  font-family: Satoshi;
+  src: url("./fonts/Satoshi-LightItalic.woff2") format("woff2"),
+       url("./fonts/Satoshi-LightItalic.woff") format("woff");
+  font-weight: 300;
+  font-style: italic;
+  font-display: swap;
+}
+
 @font-face {
   font-family: Satoshi;
   src: url("./fonts/Satoshi-Regular.woff2") format("woff2"),
@@ -63,6 +71,15 @@
   font-display: swap;
 }
 
+@font-face {
+  font-family: Satoshi;
+  src: url("./fonts/Satoshi-MediumItalic.woff2") format("woff2"),
+       url("./fonts/Satoshi-MediumItalic.woff") format("woff");
+  font-weight: 500;
+  font-style: italic;
+  font-display: swap;
+}
+
 @font-face {
   font-family: Satoshi;
   src: url("./fonts/Satoshi-Bold.woff2") format("woff2"),
@@ -72,6 +89,15 @@
   font-display: swap;
 }
 
+@font-face {
+  font-family: Satoshi;
+  src: url("./fonts/Satoshi-BoldItalic.woff2") format("woff2"),
+       url("./fonts/Satoshi-BoldItalic.woff") format("woff");
+  font-weight: 700;
+  font-style: italic;
+  font-display: swap;
+}
+
 @font-face {
   font-family: Satoshi;
   src: url("./fonts/Satoshi-Black.woff2") format("woff2"),
@@ -81,6 +107,15 @@
   font-display: swap;
 }
 
+@font-face {
+  font-family: Satoshi;
+  src: url("./fonts/Satoshi-BlackItalic.woff2") format("woff2"),
+       url("./fonts/Satoshi-BlackItalic.woff") format("woff");
+  font-weight: 900;
+  font-style: italic;
+  font-display: swap;
+}
+
 :root {
   /* =========================================================================
    * RAW RAMPS — verbatim from global.css :root after the 2026 palette

package/dist/fonts.css

@@ -4,16 +4,17 @@
  * package root. This file exists so `fonts/` can be dropped into another
  * project on its own; the paths here are relative to fonts/ itself.
  *
- * PROVENANCE
- * The production site (codecave.pro/src/styles/global.css) declares ONE face:
+ * WHY THE WEIGHTS ARE NUMBERS
+ * The vendor's own stylesheet.css cannot be used: it declares Bold and Black
+ * BOTH as `font-weight: bold`, and their italics likewise, so four cuts
+ * collide into two slots and whichever is declared last silently wins. The
+ * ten faces below bind 300/400/500/700/900 in each style explicitly, which is
+ * the whole point of shipping real cuts rather than letting a browser
+ * synthesize them.
  *
- *     @font-face { font-family: Satoshi; src: url("../assets/fonts/Satoshi-Regular.ttf"); }
- *
- * with no font-weight descriptor, which is why live 300 and 700 text is
- * browser-synthesized rather than a real cut. The brand asset upload supplied
- * genuine Light / Regular / Medium / Bold / Black cuts, so this package binds
- * them properly. Expect package output at 700 to be marginally tighter than
- * the live site until production ships the same files.
+ * The binaries are not in the npm package -- see the note in
+ * packages/brand/scripts/build.mjs -- so a consumer supplies the files and
+ * these ten declarations tell it what to supply.
  */
 
 @font-face {
@@ -25,6 +26,15 @@
   font-display: swap;
 }
 
+@font-face {
+  font-family: Satoshi;
+  src: url("./Satoshi-LightItalic.woff2") format("woff2"),
+       url("./Satoshi-LightItalic.woff") format("woff");
+  font-weight: 300;
+  font-style: italic;
+  font-display: swap;
+}
+
 @font-face {
   font-family: Satoshi;
   src: url("./Satoshi-Regular.woff2") format("woff2"),
@@ -52,6 +62,15 @@
   font-display: swap;
 }
 
+@font-face {
+  font-family: Satoshi;
+  src: url("./Satoshi-MediumItalic.woff2") format("woff2"),
+       url("./Satoshi-MediumItalic.woff") format("woff");
+  font-weight: 500;
+  font-style: italic;
+  font-display: swap;
+}
+
 @font-face {
   font-family: Satoshi;
   src: url("./Satoshi-Bold.woff2") format("woff2"),
@@ -61,6 +80,15 @@
   font-display: swap;
 }
 
+@font-face {
+  font-family: Satoshi;
+  src: url("./Satoshi-BoldItalic.woff2") format("woff2"),
+       url("./Satoshi-BoldItalic.woff") format("woff");
+  font-weight: 700;
+  font-style: italic;
+  font-display: swap;
+}
+
 @font-face {
   font-family: Satoshi;
   src: url("./Satoshi-Black.woff2") format("woff2"),
@@ -69,3 +97,12 @@
   font-style: normal;
   font-display: swap;
 }
+
+@font-face {
+  font-family: Satoshi;
+  src: url("./Satoshi-BlackItalic.woff2") format("woff2"),
+       url("./Satoshi-BlackItalic.woff") format("woff");
+  font-weight: 900;
+  font-style: italic;
+  font-display: swap;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codecavepro/brand",
-  "version": "1.5.0",
+  "version": "1.6.0",
   "description": "CODECAVE design system — colour, typography and layout tokens as CSS custom properties and as a typed module.",
   "license": "Unlicense",
   "type": "module",