docs(gravityview): split the token JSON guide off the theming page

The theming page is for someone restyling a View with CSS. Wiring the token
file into Style Dictionary or Figma is a different job for a different
reader, and it had grown into 119 lines in the middle of that page.

Moves it to /gravityview/design-tokens/ and leaves a two-sentence pointer
behind. The new page opens by saying who it is not for.

Trimmed on the way across: a statistic about how few token paths match their
CSS variable name (the one example makes the point), a paragraph on what
survives each tool's internal model, and the named `$extensions` sub-keys.
The Style Dictionary duration workaround comes back, since a page about
build pipelines is where it belongs.

Claude-Session: https://claude.ai/code/session_01QMQRQzykRFy5uhbadgm4gw

Author: zackkatz

docusaurus.config.js

@@ -100,6 +100,7 @@ const gravityview_nav = {
   items: [
     { label: 'GravityView', href: '/docs/gravityview/' },
     { label: 'Theming', href: '/gravityview/css-tokens/' },
+    { label: 'Design Tokens (JSON)', href: '/gravityview/design-tokens/' },
     {
       type: 'html',
       value: '<hr class="dropdown-separator">',

sidebars-gravityview.js

@@ -3,10 +3,10 @@
 /**
  * GravityView-specific sidebar.
  *
- * Same autogenerated tree as the shared sidebars.js, plus a manual link to the
- * CSS Design Tokens (theming) page. That page lives at /gravityview/css-tokens/
- * as a src/pages React route — it is NOT a doc under docs/gravityview/, so the
- * autogenerated sidebar can't pick it up on its own.
+ * Same autogenerated tree as the shared sidebars.js, plus manual links to the
+ * theming and design-token pages. Both live under src/pages as React routes —
+ * they are NOT docs under docs/gravityview/, so the autogenerated sidebar
+ * can't pick them up on its own.
  */
 
 /** @type {import('@docusaurus/plugin-content-docs').SidebarsConfig} */
@@ -18,6 +18,11 @@ const sidebars = {
       label: 'Theming',
       href: '/gravityview/css-tokens/',
     },
+    {
+      type: 'link',
+      label: 'Design Tokens (JSON)',
+      href: '/gravityview/design-tokens/',
+    },
   ],
 };
 

src/pages/gravityview/css-tokens.jsx

@@ -208,123 +208,66 @@ body .gv-container { --gv-color-primary: #7a1f1f; }
 :root { --gv-color-primary: #7a1f1f; }`}</code>
         </pre>
 
-        <h2>Machine-readable token files</h2>
+        <h2>Target a View with placeholders</h2>
         <p>
-          Two generated files publish this reference as data. Both rebuild from GravityView's token registry on every
-          deploy, so anything you write into them is overwritten.
+          When you enter rules in GravityView's <strong>Custom CSS</strong> field (View Settings &rarr;{' '}
+          <strong>Custom Code</strong>), GravityView swaps three placeholders for that View's own values as the page
+          loads, so you can target a single View without hardcoding its container ID:
         </p>
         <table>
           <thead>
             <tr>
-              <th>File</th>
-              <th>Format</th>
-              <th>Use it for</th>
+              <th>Placeholder</th>
+              <th>Replaced with</th>
+              <th>Example output</th>
             </tr>
           </thead>
           <tbody>
             <tr>
-              <td>
-                <a href="/api/css-tokens.tokens.json">
-                  <code>/api/css-tokens.tokens.json</code>
-                </a>
-              </td>
-              <td>
-                <a href="https://www.designtokens.org/TR/2025.10/format/">Design Tokens Format Module 2025.10</a>
-              </td>
-              <td>Design-tool interop: Style Dictionary, Terrazzo, Tokens Studio, Figma</td>
+              <td><code>VIEW_SELECTOR</code></td>
+              <td>A high-specificity CSS selector targeting only this View</td>
+              <td><code>.gv-container.gv-container-123</code></td>
             </tr>
             <tr>
-              <td>
-                <a href="/api/css-tokens.json">
-                  <code>/api/css-tokens.json</code>
-                </a>
-              </td>
-              <td>Flat GravityKit-specific JSON</td>
-              <td>The lossless record: every token, every field, no exceptions</td>
+              <td><code>VIEW_ID</code></td>
+              <td>The View's ID number</td>
+              <td><code>123</code></td>
+            </tr>
+            <tr>
+              <td><code>GF_FORM_ID</code></td>
+              <td>The connected Gravity Forms form ID</td>
+              <td><code>5</code></td>
             </tr>
           </tbody>
         </table>
         <p>
-          The DTCG file validates against the{' '}
-          <a href="https://www.designtokens.org/schemas/2025.10/format.json">
-            Design Tokens Community Group's published JSON Schema
-          </a>
-          , which the build enforces. Read <code>$extensions["com.gravitykit.tokens"].counts</code> for how many tokens
-          it carries.
-        </p>
-
-        <h3>Token paths are not CSS variable names</h3>
-        <p>
-          A token at <code>gravityview.border.entry_color</code> is the CSS variable{' '}
-          <code>--gv-entry-border-color</code>. The registry reorders and rewrites segments, so only about a fifth of
-          tokens match a naive path-to-name transform. Drive your name transform from{' '}
-          <code>$extensions["com.gravitykit.tokens"].cssVar</code>, or you will generate variables GravityView never
-          reads.
+          Prefer <code>VIEW_SELECTOR</code> for token overrides: its double-class selector
+          (<code>.gv-container.gv-container-123</code>) outranks the layered defaults, so your values win without{' '}
+          <code>!important</code> and without pinning the View ID by hand.
         </p>
         <pre>
-          <code>{`import SD from 'style-dictionary';
-
-const EXT = 'com.gravitykit.tokens';
-
-// Use the shipped CSS variable name, not the token path.
-SD.registerTransform({
-  name: 'name/gv-cssvar',
-  type: 'name',
-  transform: (t) => t.$extensions[EXT].cssVar.replace(/^--/, ''),
-});
-
-// Style Dictionary 5.x renders DTCG duration objects as "[object Object]".
-SD.registerTransform({
-  name: 'duration/css-dtcg',
-  type: 'value',
-  transitive: true,
-  filter: (t) => t.$type === 'duration' && typeof t.$value === 'object',
-  transform: (t) => \`\${t.$value.value}\${t.$value.unit}\`,
-});
-
-const sd = new SD({
-  source: ['css-tokens.tokens.json'],
-  platforms: {
-    css: {
-      prefix: '',
-      transforms: SD.hooks.transformGroups.css
-        .map((t) => (t === 'name/kebab' ? 'name/gv-cssvar' : t))
-        .concat('duration/css-dtcg'),
-      files: [{ destination: 'gravityview-tokens.css', format: 'css/variables' }],
-    },
-  },
-});
-await sd.buildAllPlatforms();`}</code>
+          <code>{`/* In GravityView's Custom CSS field. VIEW_SELECTOR resolves to this View. */
+VIEW_SELECTOR { --gv-color-primary: #7a1f1f; }`}</code>
         </pre>
         <p>
-          Terrazzo reads the file without configuration. Its <code>core/consistent-naming</code> rule defaults to
-          kebab-case and will warn on GravityView's snake_case leaf names; set{' '}
-          <code>{'{ format: "snake_case" }'}</code> on that rule to silence it.
-        </p>
-        <p>
-          <strong>File-level metadata does not survive either tool.</strong> Style Dictionary drops the root{' '}
-          <code>$description</code>, the root <code>$extensions</code> manifest and every group that has no{' '}
-          <code>$value</code>; Terrazzo keeps them only on the raw parsed document, not in its token model. Per-token{' '}
-          <code>$extensions</code> (including <code>cssVar</code>) do survive both. If you need the counts, the derived
-          list or the unrepresentable list, read them from the JSON directly rather than from a tool's output.
+          Placeholders resolve only inside a View's Custom CSS/JavaScript field, not in your theme's stylesheet.
+          Developers can add or change them with the{' '}
+          <a href="/gravityview/filters/gk-gravityview-custom-code-placeholders">
+            <code>gk/gravityview/custom-code/placeholders</code>
+          </a>{' '}
+          filter. See{' '}
+          <a href="https://www.gravitykit.com/docs/gravityview/customizing-your-views/adding-custom-css-to-your-website/#available-placeholders">
+            Adding Custom CSS to Your Website
+          </a>{' '}
+          for the full walkthrough.
         </p>
 
-        <h3>Tokens with no DTCG equivalent</h3>
-        <p>
-          DTCG has no way to express a few CSS values GravityView ships: percentage widths, <code>em</code> lengths,{' '}
-          <code>clamp()</code> and <code>min()</code>, <code>color-mix()</code>, and keywords like{' '}
-          <code>inherit</code> or <code>stretch</code>. Rather than drop them or invent a type, each appears at its
-          normal path as a group with no <code>$value</code>, carrying its description and raw CSS under{' '}
-          <code>$extensions</code>. Token-consuming tools skip these; nothing disappears silently. They are also listed
-          together under <code>$extensions["com.gravitykit.tokens"].metadataOnly</code>.
-        </p>
+        <h2>Using the tokens as data</h2>
         <p>
-          A second group of tokens is expressible but <em>resolved</em>. <code>--gv-font-size-xs</code> ships as{' '}
-          <code>calc(var(--gv-font-size-base) * 0.75)</code>, which DTCG cannot represent, so the file carries{' '}
-          <code>0.75rem</code>, its value at GravityView's defaults. Change the base font size and the browser computes
-          something different from what a Figma library synced from this file shows. Every such token says so in its{' '}
-          <code>$description</code> and is listed under{' '}
-          <code>$extensions["com.gravitykit.tokens"].derivedTokens</code>.
+          The same tokens are published as JSON, in the{' '}
+          <a href="https://www.designtokens.org/TR/2025.10/format/">Design Tokens (DTCG)</a> format, if you want to pull
+          them into Style Dictionary, Terrazzo, Tokens Studio or Figma. See{' '}
+          <a href="/gravityview/design-tokens/">Design Tokens (JSON)</a>.
         </p>
 
         <h2>Token reference</h2>

src/pages/gravityview/design-tokens.jsx

@@ -0,0 +1,130 @@
+import Layout from '@theme/Layout';
+
+export default function DesignTokensPage() {
+  return (
+    <Layout
+      title="GravityView Design Tokens (JSON)"
+      description="GravityView's design tokens as data, in the Design Tokens Community Group format, for Style Dictionary, Terrazzo, Tokens Studio and Figma."
+    >
+      <main className="container margin-vert--lg">
+        <h1>Design Tokens (JSON)</h1>
+        <p>
+          GravityView's theme tokens are published as data on every deploy, so you can pull them into a design system
+          pipeline instead of copying values by hand. If you only want to restyle a View with CSS, see{' '}
+          <a href="/gravityview/css-tokens/">Theming</a> instead.
+        </p>
+
+        <table>
+          <thead>
+            <tr>
+              <th>File</th>
+              <th>Format</th>
+            </tr>
+          </thead>
+          <tbody>
+            <tr>
+              <td>
+                <a href="/api/css-tokens.tokens.json">
+                  <code>css-tokens.tokens.json</code>
+                </a>
+              </td>
+              <td>
+                <a href="https://www.designtokens.org/TR/2025.10/format/">Design Tokens (DTCG) 2025.10</a>, for Style
+                Dictionary, Terrazzo, Tokens Studio and Figma
+              </td>
+            </tr>
+            <tr>
+              <td>
+                <a href="/api/css-tokens.json">
+                  <code>css-tokens.json</code>
+                </a>
+              </td>
+              <td>Flat JSON with every registry field, including the ones DTCG has no place for</td>
+            </tr>
+          </tbody>
+        </table>
+
+        <p>
+          The DTCG file declares its own <code>$schema</code>, so editors validate it as you work, and it is checked
+          against the{' '}
+          <a href="https://www.designtokens.org/schemas/2025.10/format.json">
+            Design Tokens Community Group's published schema
+          </a>{' '}
+          before it is published.
+        </p>
+
+        <h2>Use <code>cssVar</code>, not the token path</h2>
+        <p>
+          A token's path and its CSS variable are not the same string. <code>gravityview.border.entry_color</code> is{' '}
+          <code>--gv-entry-border-color</code>. Read the variable name from{' '}
+          <code>$extensions["com.gravitykit.tokens"].cssVar</code> so the CSS you generate matches what GravityView
+          actually reads.
+        </p>
+
+        <h2>Style Dictionary</h2>
+        <p>One custom transform points the names at the shipped CSS variables:</p>
+        <pre>
+          <code>{`import SD from 'style-dictionary';
+
+const EXT = 'com.gravitykit.tokens';
+
+SD.registerTransform({
+  name: 'name/gv-cssvar',
+  type: 'name',
+  transform: (t) => t.$extensions[EXT].cssVar.replace(/^--/, ''),
+});
+
+const sd = new SD({
+  source: ['css-tokens.tokens.json'],
+  platforms: {
+    css: {
+      prefix: '',
+      transforms: SD.hooks.transformGroups.css.map((t) =>
+        t === 'name/kebab' ? 'name/gv-cssvar' : t,
+      ),
+      files: [{ destination: 'gravityview-tokens.css', format: 'css/variables' }],
+    },
+  },
+});
+
+await sd.buildAllPlatforms();`}</code>
+        </pre>
+        <p>
+          Style Dictionary 5.x renders DTCG <code>duration</code> values as <code>[object Object]</code>, which affects
+          GravityView's transition tokens. Add this transform alongside the one above and include it in the list:
+        </p>
+        <pre>
+          <code>{`SD.registerTransform({
+  name: 'duration/css-dtcg',
+  type: 'value',
+  transitive: true,
+  filter: (t) => t.$type === 'duration' && typeof t.$value === 'object',
+  transform: (t) => \`\${t.$value.value}\${t.$value.unit}\`,
+});`}</code>
+        </pre>
+
+        <h2>Terrazzo</h2>
+        <p>
+          Terrazzo reads the file without configuration. Its <code>core/consistent-naming</code> rule warns on
+          GravityView's snake_case names until you set it to <code>{'{ format: "snake_case" }'}</code>.
+        </p>
+
+        <h2>What the DTCG file leaves out</h2>
+        <p>
+          DTCG has no way to express a handful of values GravityView ships, such as percentage widths,{' '}
+          <code>clamp()</code>, and keywords like <code>inherit</code>. Those tokens still appear at their usual path
+          with their description and raw CSS attached, but without a value, so design tools skip them.
+        </p>
+        <p>
+          A few others, like <code>--gv-font-size-xs</code>, are calculated from another token. The file carries the
+          value at GravityView's defaults and says so in the token's description, so a library synced from it can drift
+          if you change the token it derives from.
+        </p>
+        <p>
+          Both groups are listed under <code>$extensions["com.gravitykit.tokens"]</code> if you want to check them
+          programmatically, and the flat file always has the exact CSS.
+        </p>
+      </main>
+    </Layout>
+  );
+}