grailwind 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Paul Firmin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,72 @@
-# Temporary Holding Version
+# Grailwind CSS
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Heraldic blazon for [Tailwind CSS](https://tailwindcss.com). Draw coats of
+arms, or style anything else, in the language heralds have used for 800 years:
+
+```html
+<div class="escutcheon azure chevron-or">
+  <div class="charges between">
+    <i class="mullet argent"></i>
+    <i class="mullet argent"></i>
+    <i class="mullet argent"></i>
+  </div>
+</div>
+```
+
+That's *Azure, a chevron Or between three mullets Argent*: a blue shield, a
+gold chevron, and three silver stars around it.
+
+**[Read the documentation](https://pafirmin.github.io/grailwind/)** for every class, with live examples.
+
+> Grailwind is a light-hearted project at version 0.x, so class names may
+> still change.
+
+## Install
+
+Grailwind is a plugin for Tailwind CSS v4.
+
+```sh
+npm install -D grailwind
+```
+
+Import it after Tailwind:
+
+```css
+@import "tailwindcss";
+@import "grailwind";
+```
+
+This adds the heraldic tinctures (`or`, `argent`, `gules`, `azure`, `vert`,
+`purpure`, `sable`) alongside Tailwind's own colours.
+
+For a more authentic experience, import `grailwind/strict` instead, and the
+tinctures replace Tailwind's colours entirely.
+
+## What's included
+
+- **Tinctures:** a tincture on its own sets the background (`azure`), and
+  Tailwind's prefixes work as usual (`text-or`).
+- **The shield:** `escutcheon`, plus `bordure-*`.
+- **Divided fields:** `per-pale-or-gules`, `quarterly-azure-argent`,
+  `gyronny-or-sable` and more, or `per-pale`, `per-fess` and `quarterly` for
+  layout.
+- **Ordinaries:** `fess-or`, `chevron-gules`, `cross-argent`, `chief-azure`
+  and more.
+- **Charges:** `mullet`, `fleur-de-lis`, `bezant` and more, arranged by
+  number, `in-pale`, `in-fess`, `in-bend` or `between` the ordinary, or
+  placed at a named point such as `in-dexter-chief`, and sized with
+  `charge-size-*`.
+- **Your own charges:** any SVG, via `charge-[url(…)]`.
+
+## Development
+
+```sh
+npm install
+npm test        # checks both the default and strict builds
+npm run build   # builds the docs site; `npm run dev` rebuilds on change
+python3 -m http.server -d docs
+```
+
+## Licence
+
+[MIT](LICENSE)

package/charges.js

@@ -0,0 +1,163 @@
+/*
+ * Grailwind CSS: charges and their arrangement.
+ */
+import plugin from "tailwindcss/plugin";
+
+const star = (cx, cy, r, points = 5) => {
+  const coords = [];
+  for (let i = 0; i < points * 2; i++) {
+    const radius = i % 2 ? r * 0.382 : r;
+    const angle = (Math.PI / points) * i - Math.PI / 2;
+    coords.push(`${cx + radius * Math.cos(angle)},${cy + radius * Math.sin(angle)}`);
+  }
+  return `<polygon points="${coords.join(" ")}"/>`;
+};
+
+const SHAPES = {
+  roundel: `<circle cx="50" cy="50" r="46"/>`,
+  annulet: `<circle cx="50" cy="50" r="39" fill="none" stroke="#000" stroke-width="14"/>`,
+  mullet: star(50, 53, 48),
+  lozenge: `<polygon points="50,2 84,50 50,98 16,50"/>`,
+  billet: `<rect x="28" y="4" width="44" height="92"/>`,
+  crescent: `<mask id="m"><rect width="100" height="100" fill="#fff"/><circle cx="50" cy="35" r="35"/></mask><circle cx="50" cy="54" r="42" mask="url(#m)"/>`,
+  "fleur-de-lis": `
+    <path d="M50 2C61 16 64 36 55 56H45C36 36 39 16 50 2Z"/>
+    <path d="M55 56C57 38 70 24 84 26C97 29 99 46 89 52C92 44 87 37 80 39C71 42 66 50 66 56Z"/>
+    <path d="M45 56C43 38 30 24 16 26C3 29 1 46 11 52C8 44 13 37 20 39C29 42 34 50 34 56Z"/>
+    <rect x="28" y="56" width="44" height="9" rx="2"/>
+    <path d="M45 65H55C55 74 53 82 50 90C47 82 45 74 45 65Z"/>
+    <path d="M58 65C62 74 72 80 84 78C80 88 64 90 56 74Z"/>
+    <path d="M42 65C38 74 28 80 16 78C20 88 36 90 44 74Z"/>`,
+};
+
+// Roundels have their own names by tincture.
+const ROUNDELS = {
+  bezant: "or",
+  plate: "argent",
+  torteau: "gules",
+  hurt: "azure",
+  pellet: "sable",
+};
+
+// Points as [left%, top%] of the shield, plus a charge size as % of its width.
+// The default for each number of charges, e.g. three are placed 2 and 1.
+const DEFAULTS = {
+  1: { size: 50, points: [[50, 45]] },
+  2: { size: 30, points: [[50, 24], [50, 66]] },
+  3: { size: 28, points: [[28, 25], [72, 25], [50, 64]] },
+  4: { size: 24, points: [[30, 24], [70, 24], [32, 60], [68, 60]] },
+  6: { size: 20, points: [[20, 18], [50, 18], [80, 18], [35, 42], [65, 42], [50, 66]] },
+};
+
+// The points of the shield, for placing a single charge, e.g. `in-dexter-chief`.
+const POINTS = {
+  "dexter-chief": [25, 17],
+  chief: [50, 15],
+  "sinister-chief": [75, 17],
+  "honour-point": [50, 30],
+  "fess-point": [50, 45],
+  "nombril-point": [50, 60],
+  "dexter-base": [30, 72],
+  base: [50, 84],
+  "sinister-base": [70, 72],
+};
+const POINT_SIZE = 22;
+
+const ARRANGEMENTS = {
+  "in-pale": {
+    2: { size: 30, points: [[50, 24], [50, 66]] },
+    3: { size: 22, points: [[50, 16], [50, 43], [50, 70]] },
+  },
+  "in-fess": {
+    2: { size: 30, points: [[30, 45], [70, 45]] },
+    3: { size: 24, points: [[22, 45], [50, 45], [78, 45]] },
+  },
+  "in-bend": {
+    2: { size: 28, points: [[30, 26], [70, 64]] },
+    3: { size: 22, points: [[22, 16], [50, 45], [78, 74]] },
+  },
+};
+
+const svgUrl = (shape) =>
+  `url("data:image/svg+xml,${encodeURIComponent(
+    `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 100 100">${shape}</svg>`,
+  )}")`;
+
+const maskRules = (image) => ({
+  "mask-image": image,
+  "mask-size": "contain",
+  "mask-repeat": "no-repeat",
+  "mask-position": "center",
+});
+
+const place = ([left, top], size) => ({
+  left: `${left}%`,
+  top: `${top}%`,
+  width: `var(--charge-size, ${size}%)`,
+});
+
+const hasCount = (n) => `:has(> :nth-child(${n}):last-child)`;
+
+export default plugin(({ addUtilities, matchUtilities }) => {
+  // User-defined charges from images
+  matchUtilities({ charge: maskRules }, { type: ["url"] });
+
+  const utilities = {};
+
+  for (const [name, shape] of Object.entries(SHAPES)) {
+    utilities[`.${name}`] = maskRules(svgUrl(shape));
+  }
+
+  for (const [name, tincture] of Object.entries(ROUNDELS)) {
+    utilities[`.${name}`] = {
+      ...maskRules(svgUrl(SHAPES.roundel)),
+      "background-color": `var(--color-${tincture})`,
+    };
+  }
+
+  // Defaults use :where() so arrangements and `between` always win.
+  const charges = {
+    position: "absolute",
+    inset: "var(--field-top, 0%) 0 0",
+    "& > *": {
+      position: "absolute",
+      "aspect-ratio": "1",
+      translate: "-50% -50%",
+      "object-fit": "contain",
+    },
+  };
+  for (const [count, { size, points }] of Object.entries(DEFAULTS)) {
+    points.forEach((point, i) => {
+      charges[`&:where(${hasCount(count)}) > :where(:nth-child(${i + 1}))`] =
+        place(point, size);
+    });
+  }
+  utilities[".charges"] = charges;
+
+  for (const [name, counts] of Object.entries(ARRANGEMENTS)) {
+    const arrangement = {};
+    for (const [count, { size, points }] of Object.entries(counts)) {
+      points.forEach((point, i) => {
+        arrangement[`&${hasCount(count)} > :nth-child(${i + 1})`] = place(point, size);
+      });
+    }
+    utilities[`.${name}`] = arrangement;
+  }
+
+  // Positions come from the ordinary on the shield (see ordinaries.js).
+  const between = {};
+  for (let i = 1; i <= 4; i++) {
+    between[`& > :nth-child(${i})`] = {
+      left: `var(--between-${i}-x)`,
+      top: `var(--between-${i}-y)`,
+      width: "var(--charge-size, var(--between-size))",
+    };
+  }
+  utilities[".between"] = between;
+
+  for (const [name, point] of Object.entries(POINTS)) {
+    utilities[`.in-${name}`] = { ".charges > &": place(point, POINT_SIZE) };
+  }
+
+  addUtilities(utilities);
+});

package/divisions.js

@@ -0,0 +1,69 @@
+/*
+ * Grailwind CSS: field divisions as decoration.
+ */
+import plugin from "tailwindcss/plugin";
+
+const TINCTURES = ["or", "argent", "gules", "azure", "vert", "purpure", "sable"];
+
+// Each division maps (first, second) tincture colours to background rules.
+const layer = (image) => ({ "background-image": image });
+
+const DIVISIONS = {
+  // Vertical split: first on the dexter (viewer's left).
+  "per-pale": (a, b) => layer(`linear-gradient(to right, ${a} 50%, ${b} 50%)`),
+
+  // Horizontal split: first in chief.
+  "per-fess": (a, b) => layer(`linear-gradient(to bottom, ${a} 50%, ${b} 50%)`),
+
+  // Line from dexter chief to sinister base: first in the upper half.
+  // With a corner-to-corner gradient, the 50% line joins the other two corners.
+  "per-bend": (a, b) => layer(`linear-gradient(to bottom left, ${a} 50%, ${b} 50%)`),
+
+  // Line from sinister chief to dexter base: first in the upper half.
+  "per-bend-sinister": (a, b) =>
+    layer(`linear-gradient(to bottom right, ${a} 50%, ${b} 50%)`),
+
+  // Quarters 1 and 4 (dexter chief, sinister base) are the first tincture.
+  // Linear gradients rather than conic, which render jagged edges in some browsers.
+  quarterly: (a, b) => ({
+    "background-image": `linear-gradient(to right, ${a} 50%, ${b} 50%), linear-gradient(to right, ${b} 50%, ${a} 50%)`,
+    "background-size": "100% 50%, 100% 100%",
+    "background-position": "top, top",
+    "background-repeat": "no-repeat",
+  }),
+
+  // Gyronny of eight: each quarter split corner to corner. The first tincture
+  // is in the gyron just dexter of the top line. The background colour fills
+  // any sub-pixel seam between quarters.
+  gyronny: (a, b) => ({
+    "background-color": b,
+    "background-image": [
+      `linear-gradient(to bottom left, ${a} 50%, ${b} 50%)`,
+      `linear-gradient(to bottom right, ${b} 50%, ${a} 50%)`,
+      `linear-gradient(to bottom left, ${b} 50%, ${a} 50%)`,
+      `linear-gradient(to bottom right, ${a} 50%, ${b} 50%)`,
+    ].join(", "),
+    "background-size": "50% 50%",
+    "background-position": "left top, right top, right bottom, left bottom",
+    "background-repeat": "no-repeat",
+  }),
+};
+
+export default plugin(({ addUtilities }) => {
+  const utilities = {};
+
+  for (const [division, background] of Object.entries(DIVISIONS)) {
+    for (const first of TINCTURES) {
+      for (const second of TINCTURES) {
+        if (first === second) continue;
+
+        utilities[`.${division}-${first}-${second}`] = background(
+          `var(--color-${first})`,
+          `var(--color-${second})`,
+        );
+      }
+    }
+  }
+
+  addUtilities(utilities);
+});

package/grailwind.css

@@ -0,0 +1,102 @@
+/*
+ * Grailwind CSS: heraldic blazon for Tailwind v4.
+ *
+ * Import after Tailwind:
+ *   @import "tailwindcss";
+ *   @import "grailwind";
+ *
+ * Adds the tinctures alongside Tailwind's colours. For tinctures only,
+ * import "grailwind/strict" instead.
+ */
+
+@plugin "./divisions.js";
+@plugin "./ordinaries.js";
+@plugin "./charges.js";
+
+/* ---------------------------------------------------------------------------
+ * Tinctures
+ * ------------------------------------------------------------------------- */
+@theme {
+  /* Metals */
+  --color-or: #f5c518;
+  --color-argent: #ffffff;
+
+  /* Colours */
+  --color-gules: #d21f1f;
+  --color-azure: #1f4fb0;
+  --color-vert: #1d8a3c;
+  --color-purpure: #7e3a8e;
+  --color-sable: #141414;
+}
+
+/* ---------------------------------------------------------------------------
+ * Bare tinctures
+ * ------------------------------------------------------------------------- */
+@utility or      { background-color: var(--color-or); }
+@utility argent  { background-color: var(--color-argent); }
+@utility gules   { background-color: var(--color-gules); }
+@utility azure   { background-color: var(--color-azure); }
+@utility vert    { background-color: var(--color-vert); }
+@utility purpure { background-color: var(--color-purpure); }
+@utility sable   { background-color: var(--color-sable); }
+
+/* ---------------------------------------------------------------------------
+ * Field divisions
+ * ------------------------------------------------------------------------- */
+
+/* Per pale: split vertically into dexter | sinister. */
+@utility per-pale {
+  display: grid;
+  grid-auto-flow: column;
+  grid-auto-columns: 1fr;
+}
+
+/* Per fess: split horizontally into chief / base. */
+@utility per-fess {
+  display: grid;
+  grid-auto-flow: row;
+  grid-auto-rows: 1fr;
+}
+
+/* Quarterly: four quarters, numbered 1–4 across then down.
+ * Quarter 1 is dexter chief, i.e. the viewer's top left. */
+@utility quarterly {
+  display: grid;
+  grid-template-columns: 1fr 1fr;
+  grid-template-rows: 1fr 1fr;
+}
+
+/* ---------------------------------------------------------------------------
+ * Subordinaries
+ * ------------------------------------------------------------------------- */
+
+/* Bordure: a border in a given tincture, e.g. `bordure-or`. */
+@utility bordure-* {
+  border-style: solid;
+  border-width: 0.75rem;
+  border-color: --value(--color-*);
+}
+
+/* ---------------------------------------------------------------------------
+ * The shield itself
+ * ------------------------------------------------------------------------- */
+
+/* Escutcheon: a shield shape to draw arms in. */
+@utility escutcheon {
+  position: relative;
+  aspect-ratio: 5 / 6;
+  overflow: hidden;
+  border-radius: 0 0 50% 50% / 0 0 45% 45%;
+  box-shadow: 0 0 0 2px var(--color-sable);
+}
+
+/* ---------------------------------------------------------------------------
+ * Charge size
+ * ------------------------------------------------------------------------- */
+
+/* Charge width as a % of the shield, e.g. `charge-size-20` or `charge-size-[3rem]`.
+ * On a `charges` container it sizes every charge; on a charge, just that one. */
+@utility charge-size-* {
+  --charge-size: calc(--value(integer) * 1%);
+  --charge-size: --value([percentage], [length]);
+}

package/ordinaries.js

@@ -0,0 +1,68 @@
+/*
+ * Grailwind CSS: ordinaries, e.g. `fess-or`.
+ */
+import plugin from "tailwindcss/plugin";
+
+const TINCTURES = ["or", "argent", "gules", "azure", "vert", "purpure", "sable"];
+
+const ORDINARIES = {
+  pale: "polygon(35% 0, 65% 0, 65% 100%, 35% 100%)",
+  fess: "polygon(0 30%, 100% 30%, 100% 60%, 0 60%)",
+  bend: "polygon(0 0, 20% 0, 100% 80%, 100% 100%, 80% 100%, 0 20%)",
+  "bend-sinister":
+    "polygon(100% 0, 80% 0, 0 80%, 0 100%, 20% 100%, 100% 20%)",
+  chevron: "polygon(50% 25%, 100% 75%, 100% 95%, 50% 45%, 0 95%, 0 75%)",
+  cross:
+    "polygon(40% 0, 60% 0, 60% 35%, 100% 35%, 100% 55%, 60% 55%, 60% 100%, 40% 100%, 40% 55%, 0 55%, 0 35%, 40% 35%)",
+  saltire:
+    "polygon(0 0, 15% 0, 50% 35%, 85% 0, 100% 0, 100% 15%, 65% 50%, 100% 85%, 100% 100%, 85% 100%, 50% 65%, 15% 100%, 0 100%, 0 85%, 35% 50%, 0 15%)",
+  pall: "polygon(0 0, 15% 0, 50% 35%, 85% 0, 100% 0, 100% 15%, 60% 50%, 60% 100%, 40% 100%, 40% 50%, 0 15%)",
+  chief: "polygon(0 0, 100% 0, 100% 30%, 0 30%)",
+};
+
+const PSEUDO = { chief: "&::after" };
+
+// Where charges go for "between", as [left%, top%], plus their size as % of width.
+const BETWEEN = {
+  pale: { size: 18, points: [[18, 42], [82, 42]] },
+  fess: { size: 20, points: [[30, 15], [70, 15], [50, 78]] },
+  bend: { size: 24, points: [[70, 26], [30, 68]] },
+  "bend-sinister": { size: 24, points: [[30, 26], [70, 68]] },
+  chevron: { size: 22, points: [[24, 22], [76, 22], [50, 70]] },
+  cross: { size: 18, points: [[20, 17], [80, 17], [24, 72], [76, 72]] },
+  saltire: { size: 16, points: [[50, 13], [14, 50], [86, 50], [50, 84]] },
+  pall: { size: 18, points: [[50, 11], [18, 56], [82, 56]] },
+};
+
+const betweenVars = ({ size, points }) => {
+  const vars = { "--between-size": `${size}%` };
+  points.forEach(([left, top], i) => {
+    vars[`--between-${i + 1}-x`] = `${left}%`;
+    vars[`--between-${i + 1}-y`] = `${top}%`;
+  });
+  return vars;
+};
+
+export default plugin(({ addUtilities }) => {
+  const utilities = {};
+
+  for (const [ordinary, shape] of Object.entries(ORDINARIES)) {
+    for (const tincture of TINCTURES) {
+      utilities[`.${ordinary}-${tincture}`] = {
+        position: "relative",
+        ...(BETWEEN[ordinary] && betweenVars(BETWEEN[ordinary])),
+        // With a chief, everything else is drawn in the field below it.
+        ...(ordinary === "chief" && { "--field-top": "30%" }),
+        [PSEUDO[ordinary] ?? "&::before"]: {
+          content: '""',
+          position: "absolute",
+          inset: ordinary === "chief" ? "0" : "var(--field-top, 0%) 0 0",
+          "background-color": `var(--color-${tincture})`,
+          "clip-path": shape,
+        },
+      };
+    }
+  }
+
+  addUtilities(utilities);
+});

package/package.json

@@ -1,6 +1,54 @@
 {
   "name": "grailwind",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "scripts": {
+    "build": "tailwindcss -i docs/app.css -o docs/site.css",
+    "dev": "tailwindcss -i docs/app.css -o docs/site.css --watch",
+    "test": "node test/modes.mjs"
+  },
+  "keywords": [
+    "tailwindcss",
+    "tailwind",
+    "heraldry",
+    "blazon",
+    "css"
+  ],
+  "author": "Paul Firmin",
+  "license": "MIT",
+  "description": "Heraldic blazon for Tailwind CSS: tinctures, divisions, ordinaries and charges",
+  "devDependencies": {
+    "@tailwindcss/cli": "^4.3.3",
+    "tailwindcss": "^4.3.3"
+  },
+  "type": "module",
+  "style": "grailwind.css",
+  "exports": {
+    ".": {
+      "style": "./grailwind.css",
+      "default": "./grailwind.css"
+    },
+    "./strict": {
+      "style": "./strict.css",
+      "default": "./strict.css"
+    }
+  },
+  "files": [
+    "grailwind.css",
+    "divisions.js",
+    "ordinaries.js",
+    "charges.js",
+    "strict.css",
+    "palette-reset.css"
+  ],
+  "peerDependencies": {
+    "tailwindcss": "^4.0.0"
+  },
+  "homepage": "https://pafirmin.github.io/grailwind/",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/pafirmin/grailwind.git"
+  },
+  "bugs": {
+    "url": "https://github.com/pafirmin/grailwind/issues"
+  }
+}

package/palette-reset.css

@@ -0,0 +1,4 @@
+/* Removes Tailwind's colours. Used by strict.css. */
+@theme {
+  --color-*: initial;
+}

package/strict.css

@@ -0,0 +1,5 @@
+/*
+ * Grailwind CSS, strict: the tinctures replace Tailwind's colours entirely.
+ */
+@import "./palette-reset.css";
+@import "./grailwind.css";