@regardio/brand 0.8.1 → 0.9.0

package/dist/generated/sprites/compass-sprite.d.mts

@@ -1,7 +1,8 @@
 import React, { SVGProps } from "react";
 
 //#region src/generated/sprites/compass-sprite.d.ts
-type CompassSpriteId = "bridges.perspectives.contradicts" | "bridges.perspectives.enables" | "bridges.perspectives.extends" | "bridges.perspectives.fulfills" | "bridges.perspectives.matches" | "bridges.perspectives.supports" | "bridges.perspectives" | "facets.elements.assets" | "facets.elements.means" | "facets.elements.people" | "facets.elements.spaces" | "facets.elements" | "facets.elements.things" | "facets.elements.times" | "facets.steps.accord.bottom" | "facets.steps.accord.top" | "facets.steps.action.bottom" | "facets.steps.action.top" | "facets.steps.effect.bottom" | "facets.steps.effect.top" | "facets.steps.essence.bottom" | "facets.steps.essence.top" | "facets.steps.impulse.bottom" | "facets.steps.impulse.top" | "facets.steps.signal.bottom" | "facets.steps.signal.top" | "facets.steps" | "pursuit.prospect.flourishing" | "zest.leisure.breeze" | "zest.leisure.calm" | "zest.leisure.contemplation" | "zest.leisure.distance" | "zest.leisure.indulgence" | "zest.leisure.inspiration" | "zest.leisure.movement" | "zest.leisure.nearness" | "zest.leisure.nourishment" | "zest.leisure.refreshment" | "zest.leisure.relaxation" | "zest.leisure.relief" | "zest.leisure" | "zest.motivators.flexibility" | "zest.motivators.orientation" | "zest.motivators.pathways" | "zest.motivators.possibilities" | "zest.motivators.strength" | "zest.motivators.structure" | "zest.motivators";
+type CompassSpriteId = "bridge-view-contradicts" | "bridge-view-enables" | "bridge-view-extends" | "bridge-view-fulfills" | "bridge-view-matches" | "bridge-view-supports" | "bridges-views" | "facet-element-means" | "facet-element-memories" | "facet-element-people" | "facet-element-spaces" | "facet-element-things" | "facet-element-times" | "facet-step-accord-bottom" | "facet-step-accord-top" | "facet-step-action-bottom" | "facet-step-action-top" | "facet-step-effect-bottom" | "facet-step-effect-top" | "facet-step-essence-bottom" | "facet-step-essence-top" | "facet-step-impulse-bottom" | "facet-step-impulse-top" | "facet-step-signal-bottom" | "facet-step-signal-top" | "facets-elements" | "facets-steps" | "pursuit-foundation-flourishing" | "pursuit-foundation-pointer" | "source-drive-flexibility" | "source-drive-orientation" | "source-drive-pathways" | "source-drive-possibilities" | "source-drive-strength" | "source-drive-structure" | "source-leisure-breeze" | "source-leisure-calm" | "source-leisure-contemplation" | "source-leisure-distance" | "source-leisure-indulgence" | "source-leisure-inspiration" | "source-leisure-movement" | "source-leisure-nearness" | "source-leisure-nourishment" | "source-leisure-refreshment" | "source-leisure-relaxation" | "source-leisure-relief" | "sources-drive" | "sources-leisure";
+declare const compassSpriteIds: CompassSpriteId[];
 interface CompassSpriteProps extends Omit<SVGProps<SVGSVGElement>, "children"> {
   /** The sprite ID to render */
   id: CompassSpriteId;
@@ -13,8 +14,8 @@ interface CompassSpriteProps extends Omit<SVGProps<SVGSVGElement>, "children"> {
 *
 * Usage:
 * ```tsx
-* <CompassSprite id="facet.step.action.bottom" className="w-8 h-8" />
-* <CompassSprite id="spark.motivator.possibilities" size={24} />
+* <CompassSprite id="facet-step-action-bottom" className="w-8 h-8" />
+* <CompassSprite id="source-drive-possibilities" size={24} />
 * ```
 *
 * Note: The compass-base.svg sprite file must be available in your application.
@@ -28,4 +29,4 @@ declare function CompassSprite({
   ...props
 }: CompassSpriteProps): React.JSX.Element;
 //#endregion
-export { CompassSprite, CompassSprite as default, CompassSpriteId, CompassSpriteProps };
+export { CompassSprite, CompassSprite as default, CompassSpriteId, CompassSpriteProps, compassSpriteIds };

package/dist/generated/sprites/compass-sprite.mjs

@@ -1,12 +1,63 @@
 import { jsx } from "react/jsx-runtime";
 //#region src/generated/sprites/compass-sprite.tsx
+const compassSpriteIds = [
+	"bridge-view-contradicts",
+	"bridge-view-enables",
+	"bridge-view-extends",
+	"bridge-view-fulfills",
+	"bridge-view-matches",
+	"bridge-view-supports",
+	"bridges-views",
+	"facet-element-means",
+	"facet-element-memories",
+	"facet-element-people",
+	"facet-element-spaces",
+	"facet-element-things",
+	"facet-element-times",
+	"facet-step-accord-bottom",
+	"facet-step-accord-top",
+	"facet-step-action-bottom",
+	"facet-step-action-top",
+	"facet-step-effect-bottom",
+	"facet-step-effect-top",
+	"facet-step-essence-bottom",
+	"facet-step-essence-top",
+	"facet-step-impulse-bottom",
+	"facet-step-impulse-top",
+	"facet-step-signal-bottom",
+	"facet-step-signal-top",
+	"facets-elements",
+	"facets-steps",
+	"pursuit-foundation-flourishing",
+	"pursuit-foundation-pointer",
+	"source-drive-flexibility",
+	"source-drive-orientation",
+	"source-drive-pathways",
+	"source-drive-possibilities",
+	"source-drive-strength",
+	"source-drive-structure",
+	"source-leisure-breeze",
+	"source-leisure-calm",
+	"source-leisure-contemplation",
+	"source-leisure-distance",
+	"source-leisure-indulgence",
+	"source-leisure-inspiration",
+	"source-leisure-movement",
+	"source-leisure-nearness",
+	"source-leisure-nourishment",
+	"source-leisure-refreshment",
+	"source-leisure-relaxation",
+	"source-leisure-relief",
+	"sources-drive",
+	"sources-leisure"
+];
 /**
 * Renders a sprite from the compass-base.svg sprite sheet.
 *
 * Usage:
 * ```tsx
-* <CompassSprite id="facet.step.action.bottom" className="w-8 h-8" />
-* <CompassSprite id="spark.motivator.possibilities" size={24} />
+* <CompassSprite id="facet-step-action-bottom" className="w-8 h-8" />
+* <CompassSprite id="source-drive-possibilities" size={24} />
 * ```
 *
 * Note: The compass-base.svg sprite file must be available in your application.
@@ -28,4 +79,4 @@ function CompassSprite({ id, size, width, height, ...props }) {
 	});
 }
 //#endregion
-export { CompassSprite, CompassSprite as default };
+export { CompassSprite, CompassSprite as default, compassSpriteIds };

package/dist/styles/grid.css

@@ -1,10 +1,43 @@
 /**
- * Grid Utilities
- * Regardio's standard container and grid layout system
+ * Grid System
+ * Fluid grid based on Utopia scales for perfect square cells
  *
- * Uses tokens defined in tokens.css:
- * - --spacing-grid-max: Maximum container width
- * - --spacing-grid-gutter: Horizontal padding/gap
+ * FLUID GRID APPROACH:
+ * The grid uses fluid spacing where gutter width scales proportionally with viewport.
+ * When grid-gutter equals column width, and the same value is used for row gaps,
+ * cells become perfect squares automatically - no aspect-ratio calculations needed.
+ *
+ * CONFIGURATION:
+ * Define these tokens in your application (see utopia.css for fluid scales):
+ *
+ * ```css
+ * :root {
+ *   --spacing-grid-max: 162.5rem;           // Maximum container width
+ *   --spacing-grid-gutter: var(--space-m);  // Fluid gutter (column + row gaps)
+ * }
+ * ```
+ *
+ * USAGE WITH REACT GRID:
+ * Use @regardio/react Grid component for responsive layouts:
+ *
+ * ```tsx
+ * <Grid.Root flow="dense">
+ *   <Grid.Item span={12} spanMd={6} spanLg={4}>
+ *     Content automatically becomes square when gutter = column width
+ *   </Grid.Item>
+ * </Grid.Root>
+ * ```
+ *
+ * FLUID SPACING:
+ * Use fluid-tailwindcss utilities instead of custom classes:
+ * - fl-gap-s/m: Fluid gap from --space-s to --space-m
+ * - fl-py-m/l: Fluid vertical padding from --space-m to --space-l
+ * - flex flex-col fl-gap-xs/s: Stack with fluid gap
+ * - flex flex-wrap fl-gap-2xs/xs: Cluster with fluid gap
+ *
+ * UTOPIA CALCULATOR:
+ * Generate fluid scales at https://utopia.fyi/grid/calculator
+ * Link fluid type, spacing, and grid for a cohesive system.
  */
 @layer components {
   /**
@@ -19,6 +52,8 @@
 
   /**
    * 12-column CSS Grid with container queries
+   * Uses CSS custom properties for configurability:
+   * - --spacing-grid-gutter: Gap between grid items
    */
   .u-grid {
     display: grid;
@@ -57,4 +92,11 @@
   .u-grid-quarter {
     grid-column: span 3;
   }
+
+  /**
+   * Sixth-width grid item spanning 2 columns
+   */
+  .u-grid-sixth {
+    grid-column: span 2;
+  }
 }

package/dist/styles/index.css

@@ -17,6 +17,9 @@
 /* Design tokens (breakpoints, containers, semantic colors, shadows) */
 @import "./tokens.css";
 
+/* Utopia fluid scales (type and spacing) */
+@import "./utopia.css";
+
 /* Fluid typography system with Georama Variable font */
 @import "./typography.css";
 

package/dist/styles/tokens.css

@@ -67,7 +67,7 @@
 
 :root {
   /* Grid system configuration */
-  --spacing-grid-max: 1200px;
+  --spacing-grid-max: 2560px;
   --spacing-grid-gutter: 1.5rem;
 
   /* Elevation shadows - light mode */

package/dist/styles/typography.css

@@ -1,7 +1,11 @@
 /**
  * Typography System
- * Fluid typography using viewport-based scaling with Georama Variable font
- * Scales automatically between 320px and 2560px viewports
+ * Fluid typography using Utopia scales with Georama Variable font
+ *
+ * Uses Utopia --step-* tokens for fluid type scaling.
+ * Base font size (--step-0) applied to body, not html, to avoid interfering with other tools.
+ *
+ * @link https://utopia.fyi/type/calculator
  */
 
 @import "@fontsource-variable/georama";
@@ -12,22 +16,6 @@
   --font-mono:
     ui-monospace, "Cascadia Code", "Source Code Pro", Menlo, Consolas, "DejaVu Sans Mono", monospace;
 
-  /* Fluid font sizes - viewport-based scaling */
-  /* Base: 16px at 320px viewport, scales to 18px at 2560px */
-  --font-size-xs: clamp(0.75rem, 0.7455rem + 0.0196vw, 0.84rem);
-  --font-size-sm: clamp(0.875rem, 0.8696rem + 0.0234vw, 0.98rem);
-  --font-size-base: clamp(1rem, 0.9937rem + 0.0272vw, 1.125rem);
-  --font-size-lg: clamp(1.125rem, 1.1179rem + 0.0308vw, 1.266rem);
-  --font-size-xl: clamp(1.25rem, 1.242rem + 0.0348vw, 1.406rem);
-  --font-size-2xl: clamp(1.5rem, 1.4902rem + 0.0424vw, 1.688rem);
-  --font-size-3xl: clamp(1.875rem, 1.8627rem + 0.0533vw, 2.109rem);
-  --font-size-4xl: clamp(2.25rem, 2.2353rem + 0.0641vw, 2.531rem);
-  --font-size-5xl: clamp(3rem, 2.9804rem + 0.0848vw, 3.375rem);
-  --font-size-6xl: clamp(3.75rem, 3.7255rem + 0.106vw, 4.219rem);
-  --font-size-7xl: clamp(4.5rem, 4.4706rem + 0.1272vw, 5.063rem);
-  --font-size-8xl: clamp(6rem, 5.9608rem + 0.1696vw, 6.75rem);
-  --font-size-9xl: clamp(8rem, 7.9412rem + 0.2544vw, 9rem);
-
   /* Line heights */
   --line-height-none: 1;
   --line-height-tight: 1.25;
@@ -46,15 +34,9 @@
 }
 
 @layer base {
-  /* Fluid root font size - scales from 16px at 320px to 27px at 2560px */
-  /* This makes ALL rem values fluid throughout the system */
-  html {
-    font-size: clamp(16px, 14.429px + 0.4911vw, 27px);
-  }
-
   body {
     font-family: var(--font-sans);
-    font-size: var(--font-size-base);
+    font-size: var(--step-0);
     font-feature-settings:
       "liga" 1,
       "dlig" 1,
@@ -66,41 +48,41 @@
     line-height: var(--line-height-normal);
   }
 
-  /* Headings with fluid sizing */
+  /* Headings with Utopia fluid sizing */
   h1 {
-    font-size: var(--font-size-5xl);
+    font-size: var(--step-5);
     font-weight: 700;
     line-height: var(--line-height-tight);
     letter-spacing: var(--letter-spacing-tight);
   }
 
   h2 {
-    font-size: var(--font-size-4xl);
+    font-size: var(--step-4);
     font-weight: 700;
     line-height: var(--line-height-tight);
     letter-spacing: var(--letter-spacing-tight);
   }
 
   h3 {
-    font-size: var(--font-size-3xl);
+    font-size: var(--step-3);
     font-weight: 600;
     line-height: var(--line-height-snug);
   }
 
   h4 {
-    font-size: var(--font-size-2xl);
+    font-size: var(--step-2);
     font-weight: 600;
     line-height: var(--line-height-snug);
   }
 
   h5 {
-    font-size: var(--font-size-xl);
+    font-size: var(--step-1);
     font-weight: 600;
     line-height: var(--line-height-snug);
   }
 
   h6 {
-    font-size: var(--font-size-lg);
+    font-size: var(--step-0);
     font-weight: 600;
     line-height: var(--line-height-normal);
   }

package/dist/styles/utopia.css

@@ -0,0 +1,59 @@
+/**
+ * Utopia Fluid Scales
+ * Generated from https://utopia.fyi
+ *
+ * This file defines fluid type and spacing scales that adapt smoothly across viewports.
+ * Use these tokens with fluid-tailwindcss utilities or directly in your CSS.
+ *
+ * TYPOGRAPHY:
+ * Apply --step-0 to body or main container (not html to avoid interfering with other tools)
+ * Use --step-1 through --step-7 for headings and larger text
+ * Use --step--1 and --step--2 for smaller text
+ *
+ * SPACING:
+ * Use with fluid-tailwindcss: fl-gap-s/m, fl-py-m/l, etc.
+ * Or use directly: gap: var(--space-s-m)
+ *
+ * GRID:
+ * Configure grid gutter with fluid spacing for perfect square cells
+ */
+
+/* @link https://utopia.fyi/type/calculator?c=320,16,1.2,2560,26,1.25,7,2,&s=0.75|0.5|0.25,1.5|2|3|4|6,2xs-2xl&g=2xs,2xl,2xl,12 */
+:root {
+  --step--2: clamp(0.6944rem, 0.6451rem + 0.2468vw, 1.04rem);
+  --step--1: clamp(0.8333rem, 0.7667rem + 0.3333vw, 1.3rem);
+  --step-0: clamp(1rem, 0.9107rem + 0.4464vw, 1.625rem);
+  --step-1: clamp(1.2rem, 1.0813rem + 0.5938vw, 2.0313rem);
+  --step-2: clamp(1.44rem, 1.283rem + 0.785vw, 2.5391rem);
+  --step-3: clamp(1.728rem, 1.5215rem + 1.0327vw, 3.1738rem);
+  --step-4: clamp(2.0736rem, 1.8031rem + 1.3526vw, 3.9673rem);
+  --step-5: clamp(2.4883rem, 2.1354rem + 1.7648vw, 4.9591rem);
+  --step-6: clamp(2.986rem, 2.527rem + 2.2949vw, 6.1989rem);
+  --step-7: clamp(3.5832rem, 2.9881rem + 2.9753vw, 7.7486rem);
+}
+
+/* @link https://utopia.fyi/space/calculator?c=320,16,1.2,2560,26,1.25,7,2,&s=0.75|0.5|0.25,1.5|2|3|4|6,2xs-2xl&g=2xs,2xl,2xl,12 */
+:root {
+  --space-3xs: clamp(0.25rem, 0.2232rem + 0.1339vw, 0.4375rem);
+  --space-2xs: clamp(0.5rem, 0.4554rem + 0.2232vw, 0.8125rem);
+  --space-xs: clamp(0.75rem, 0.6786rem + 0.3571vw, 1.25rem);
+  --space-s: clamp(1rem, 0.9107rem + 0.4464vw, 1.625rem);
+  --space-m: clamp(1.5rem, 1.3661rem + 0.6696vw, 2.4375rem);
+  --space-l: clamp(2rem, 1.8214rem + 0.8929vw, 3.25rem);
+  --space-xl: clamp(3rem, 2.7321rem + 1.3393vw, 4.875rem);
+  --space-2xl: clamp(4rem, 3.6429rem + 1.7857vw, 6.5rem);
+  --space-3xl: clamp(6rem, 5.4643rem + 2.6786vw, 9.75rem);
+
+  /* One-up pairs */
+  --space-3xs-2xs: clamp(0.25rem, 0.1696rem + 0.4018vw, 0.8125rem);
+  --space-2xs-xs: clamp(0.5rem, 0.3929rem + 0.5357vw, 1.25rem);
+  --space-xs-s: clamp(0.75rem, 0.625rem + 0.625vw, 1.625rem);
+  --space-s-m: clamp(1rem, 0.7946rem + 1.0268vw, 2.4375rem);
+  --space-m-l: clamp(1.5rem, 1.25rem + 1.25vw, 3.25rem);
+  --space-l-xl: clamp(2rem, 1.5893rem + 2.0536vw, 4.875rem);
+  --space-xl-2xl: clamp(3rem, 2.5rem + 2.5vw, 6.5rem);
+  --space-2xl-3xl: clamp(4rem, 3.1786rem + 4.1071vw, 9.75rem);
+
+  /* Custom pairs */
+  --space-2xs-2xl: clamp(0.5rem, -0.3571rem + 4.2857vw, 6.5rem);
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://www.schemastore.org/package.json",
   "name": "@regardio/brand",
-  "version": "0.8.1",
+  "version": "0.9.0",
   "private": false,
   "description": "Regardio Brand Assets",
   "homepage": "https://github.com/regardio/brand#readme",
@@ -65,33 +65,33 @@
       "import": "./dist/generated/icons/regardio-logo-mono-light.mjs",
       "types": "./dist/generated/icons/regardio-logo-mono-light.d.mts"
     },
-    "./icons/regardio-system-bridge-icon": {
-      "import": "./dist/generated/icons/regardio-system-bridge-icon.mjs",
-      "types": "./dist/generated/icons/regardio-system-bridge-icon.d.mts"
-    },
-    "./icons/regardio-system-circle-icon": {
-      "import": "./dist/generated/icons/regardio-system-circle-icon.mjs",
-      "types": "./dist/generated/icons/regardio-system-circle-icon.d.mts"
-    },
-    "./icons/regardio-system-facet-icon": {
-      "import": "./dist/generated/icons/regardio-system-facet-icon.mjs",
-      "types": "./dist/generated/icons/regardio-system-facet-icon.d.mts"
-    },
     "./icons/regardio-system-icon": {
       "import": "./dist/generated/icons/regardio-system-icon.mjs",
       "types": "./dist/generated/icons/regardio-system-icon.d.mts"
     },
-    "./icons/regardio-system-plan-icon": {
-      "import": "./dist/generated/icons/regardio-system-plan-icon.mjs",
-      "types": "./dist/generated/icons/regardio-system-plan-icon.d.mts"
+    "./icons/system-layer-bridges-icon": {
+      "import": "./dist/generated/icons/system-layer-bridges-icon.mjs",
+      "types": "./dist/generated/icons/system-layer-bridges-icon.d.mts"
+    },
+    "./icons/system-layer-circles-icon": {
+      "import": "./dist/generated/icons/system-layer-circles-icon.mjs",
+      "types": "./dist/generated/icons/system-layer-circles-icon.d.mts"
+    },
+    "./icons/system-layer-facets-icon": {
+      "import": "./dist/generated/icons/system-layer-facets-icon.mjs",
+      "types": "./dist/generated/icons/system-layer-facets-icon.d.mts"
+    },
+    "./icons/system-layer-sources-icon": {
+      "import": "./dist/generated/icons/system-layer-sources-icon.mjs",
+      "types": "./dist/generated/icons/system-layer-sources-icon.d.mts"
     },
-    "./icons/regardio-system-pursuit-icon": {
-      "import": "./dist/generated/icons/regardio-system-pursuit-icon.mjs",
-      "types": "./dist/generated/icons/regardio-system-pursuit-icon.d.mts"
+    "./icons/system-layer-plans-icon": {
+      "import": "./dist/generated/icons/system-layer-plans-icon.mjs",
+      "types": "./dist/generated/icons/system-layer-plans-icon.d.mts"
     },
-    "./icons/regardio-system-spark-icon": {
-      "import": "./dist/generated/icons/regardio-system-spark-icon.mjs",
-      "types": "./dist/generated/icons/regardio-system-spark-icon.d.mts"
+    "./icons/system-layer-pursuits-icon": {
+      "import": "./dist/generated/icons/system-layer-pursuits-icon.mjs",
+      "types": "./dist/generated/icons/system-layer-pursuits-icon.d.mts"
     },
     "./sprites/compass-sprite": {
       "import": "./dist/generated/sprites/compass-sprite.mjs",
@@ -108,9 +108,7 @@
     "src/components"
   ],
   "scripts": {
-    "build": "exec-s build:tsdown build:copy-styles",
-    "build:copy-styles": "mkdir -p dist/styles && cp -r src/styles/* dist/styles/",
-    "build:tsdown": "tsdown",
+    "build": "tsdown",
     "clean": "exec-clean .turbo dist src/generated",
     "dev": "tsdown --watch",
     "fix": "exec-s fix:pkg fix:md fix:biome",
@@ -140,15 +138,15 @@
   },
   "dependencies": {
     "@fontsource-variable/georama": "5.2.8",
-    "@regardio/react": "^0.8.1",
-    "@regardio/tailwind": "^0.4.2"
+    "@regardio/react": "^0.8.2",
+    "@regardio/tailwind": "^0.4.3"
   },
   "devDependencies": {
-    "@regardio/dev": "^1.18.0",
-    "@storybook/addon-a11y": "10.3.0",
-    "@storybook/addon-docs": "10.3.0",
-    "@storybook/addon-vitest": "10.3.0",
-    "@storybook/react-vite": "10.3.0",
+    "@regardio/dev": "^1.18.2",
+    "@storybook/addon-a11y": "10.3.3",
+    "@storybook/addon-docs": "10.3.3",
+    "@storybook/addon-vitest": "10.3.3",
+    "@storybook/react-vite": "10.3.3",
     "@svgr/cli": "8.1.0",
     "@svgr/plugin-jsx": "8.1.0",
     "@svgr/plugin-svgo": "8.1.0",
@@ -158,20 +156,21 @@
     "@types/react": "19.2.14",
     "@types/react-dom": "19.2.3",
     "@vitejs/plugin-react": "6.0.1",
-    "@vitest/browser-playwright": "4.1.0",
-    "@vitest/coverage-v8": "4.1.0",
-    "@vitest/ui": "4.1.0",
+    "@vitest/browser-playwright": "4.1.1",
+    "@vitest/coverage-v8": "4.1.1",
+    "@vitest/ui": "4.1.1",
     "linkedom": "0.18.12",
     "node-html-parser": "7.1.0",
     "playwright": "1.58.2",
     "react": "19.2.4",
     "react-dom": "19.2.4",
-    "storybook": "10.3.0",
+    "storybook": "10.3.3",
     "svgo": "4.0.1",
     "tailwindcss": "4.2.2",
-    "tsdown": "0.21.4",
-    "typescript": "5.9.3",
-    "vite": "8.0.0",
-    "vitest": "4.1.0"
+    "tsdown": "0.21.5",
+    "tsx": "4.21.0",
+    "typescript": "6.0.2",
+    "vite": "8.0.2",
+    "vitest": "4.1.1"
   }
 }

package/src/styles/grid.css

@@ -1,10 +1,43 @@
 /**
- * Grid Utilities
- * Regardio's standard container and grid layout system
+ * Grid System
+ * Fluid grid based on Utopia scales for perfect square cells
  *
- * Uses tokens defined in tokens.css:
- * - --spacing-grid-max: Maximum container width
- * - --spacing-grid-gutter: Horizontal padding/gap
+ * FLUID GRID APPROACH:
+ * The grid uses fluid spacing where gutter width scales proportionally with viewport.
+ * When grid-gutter equals column width, and the same value is used for row gaps,
+ * cells become perfect squares automatically - no aspect-ratio calculations needed.
+ *
+ * CONFIGURATION:
+ * Define these tokens in your application (see utopia.css for fluid scales):
+ *
+ * ```css
+ * :root {
+ *   --spacing-grid-max: 162.5rem;           // Maximum container width
+ *   --spacing-grid-gutter: var(--space-m);  // Fluid gutter (column + row gaps)
+ * }
+ * ```
+ *
+ * USAGE WITH REACT GRID:
+ * Use @regardio/react Grid component for responsive layouts:
+ *
+ * ```tsx
+ * <Grid.Root flow="dense">
+ *   <Grid.Item span={12} spanMd={6} spanLg={4}>
+ *     Content automatically becomes square when gutter = column width
+ *   </Grid.Item>
+ * </Grid.Root>
+ * ```
+ *
+ * FLUID SPACING:
+ * Use fluid-tailwindcss utilities instead of custom classes:
+ * - fl-gap-s/m: Fluid gap from --space-s to --space-m
+ * - fl-py-m/l: Fluid vertical padding from --space-m to --space-l
+ * - flex flex-col fl-gap-xs/s: Stack with fluid gap
+ * - flex flex-wrap fl-gap-2xs/xs: Cluster with fluid gap
+ *
+ * UTOPIA CALCULATOR:
+ * Generate fluid scales at https://utopia.fyi/grid/calculator
+ * Link fluid type, spacing, and grid for a cohesive system.
  */
 @layer components {
   /**
@@ -19,6 +52,8 @@
 
   /**
    * 12-column CSS Grid with container queries
+   * Uses CSS custom properties for configurability:
+   * - --spacing-grid-gutter: Gap between grid items
    */
   .u-grid {
     display: grid;
@@ -57,4 +92,11 @@
   .u-grid-quarter {
     grid-column: span 3;
   }
+
+  /**
+   * Sixth-width grid item spanning 2 columns
+   */
+  .u-grid-sixth {
+    grid-column: span 2;
+  }
 }

package/src/styles/index.css

@@ -17,6 +17,9 @@
 /* Design tokens (breakpoints, containers, semantic colors, shadows) */
 @import "./tokens.css";
 
+/* Utopia fluid scales (type and spacing) */
+@import "./utopia.css";
+
 /* Fluid typography system with Georama Variable font */
 @import "./typography.css";
 

package/src/styles/tokens.css

@@ -67,7 +67,7 @@
 
 :root {
   /* Grid system configuration */
-  --spacing-grid-max: 1200px;
+  --spacing-grid-max: 2560px;
   --spacing-grid-gutter: 1.5rem;
 
   /* Elevation shadows - light mode */