@jay-framework/design-system-validator 0.22.2 → 0.24.0

package/agent-kit/aiditor/settings.template.yaml

@@ -0,0 +1,2 @@
+label: Design themes
+route: /design-system/settings

package/agent-kit/designer/design-system.md

@@ -97,7 +97,7 @@ Use the token values directly in your `<style>` blocks:
 }
 ```
 
-CSS custom properties (`var(--name)`) are resolved statically when defined in `:root`. Unresolvable vars are accepted without validation.
+CSS custom properties (`var(--name)`) are resolved statically when defined in the page's CSS (inline `<style>` or linked local stylesheets). Variables that are used but never defined are flagged as warnings.
 
 ## Breakpoints
 
@@ -132,12 +132,18 @@ The `components` section defines expected styles for HTML elements (matched by c
 
 When a value intentionally breaks the design system, exempt it:
 
-**In CSS** — add a comment after the declaration:
+**In CSS** — add a comment on the same line or the line immediately after the declaration:
 
 ```css
 .hero {
   padding: 7.5rem 0; /* design-system: allow */
 }
+
+/* or on the next line: */
+.hero {
+  padding: 7.5rem 0;
+  /* design-system: allow */
+}
 ```
 
 **On elements** — add the `jay-design="allow"` attribute:
@@ -213,6 +219,14 @@ These are the errors the validator produces. Use them to align your CSS with the
   Suggestion: Use a DESIGN.md breakpoint: mobile (600px), tablet (768px), desktop (1024px)
 ```
 
+**Undefined CSS variable:**
+
+```
+⚠ CSS variable "--color-surface-tint" is used but never defined
+  Suggestion: Define --color-surface-tint in a :root block, or replace with a DESIGN.md token value directly.
+  To suppress: add /* design-system: allow */ on the same line or the line after the declaration.
+```
+
 **Low contrast:**
 
 ```

package/agent-kit/designer/font-fallback-patterns.md

@@ -0,0 +1,78 @@
+# Font Fallback Patterns
+
+## Why metric-matched fallbacks matter
+
+When a web font loads via `font-display: swap`, the browser renders a system fallback font first. Differences in vertical metrics (ascent, descent, line-gap) and horizontal metrics (character width) between the web font and fallback cause visible layout jumps — known as Flash of Unstyled Text (FOUT) — and degrade Cumulative Layout Shift (CLS).
+
+A metric-matched fallback `@font-face` overrides the system font's metrics to match the web font, so the swap is visually seamless.
+
+## Using the action
+
+Generate a fallback `@font-face` for any known Google Font or system font:
+
+```bash
+npx jay-stack-cli action design-system-validator/fontFallback --input '{"primary":"Inter","fallback":"Arial"}'
+```
+
+This outputs the CSS you need:
+
+```css
+@font-face {
+  font-family: 'Inter Fallback';
+  src: local('Arial'), local('ArialMT');
+  ascent-override: 90.44%;
+  descent-override: 22.52%;
+  line-gap-override: 0%;
+  size-adjust: 107.12%;
+}
+```
+
+Then add the fallback to your `font-family` stack:
+
+```css
+body {
+  font-family: 'Inter', 'Inter Fallback', sans-serif;
+}
+```
+
+## Where to place the fallback CSS
+
+- **DESIGN.md**: If your design system defines fonts in the frontmatter, add the fallback `@font-face` to the page's `<style>` block or a shared stylesheet
+- **Page `<head>` styles**: For per-page fonts, place the `@font-face` in the page's `<style>` tag
+
+## Common font pairs
+
+| Web font         | Fallback | Category   |
+| ---------------- | -------- | ---------- |
+| Inter            | Arial    | sans-serif |
+| Roboto           | Arial    | sans-serif |
+| Open Sans        | Arial    | sans-serif |
+| Playfair Display | Georgia  | serif      |
+| Merriweather     | Georgia  | serif      |
+| Lora             | Georgia  | serif      |
+
+## Manual pattern
+
+If the action doesn't support your font, you can write the fallback manually. The key CSS properties are:
+
+- `size-adjust` — scales the fallback to match the web font's character width
+- `ascent-override` — matches the space above the baseline
+- `descent-override` — matches the space below the baseline
+- `line-gap-override` — matches the inter-line spacing
+
+```css
+@font-face {
+  font-family: 'MyFont-Fallback';
+  src: local('Arial');
+  size-adjust: <value>%;
+  ascent-override: <value>%;
+  descent-override: <value>%;
+  line-gap-override: <value>%;
+}
+```
+
+## Validation
+
+The `font-fallbacks` validator detects `@font-face` rules that load from a URL without a companion metric-matched fallback. It checks both page CSS and DESIGN.md typography tokens.
+
+To suppress a false positive, use the standard `/* design-system: allow */` comment after the `font-family` declaration.

package/dist/actions/font-fallback.jay-action

@@ -0,0 +1,12 @@
+name: fontFallback
+description: >
+  Generate a metric-matched fallback @font-face for a web font to prevent layout shift (CLS).
+  Uses pre-computed metrics from @capsizecss/metrics for known Google and system fonts.
+
+inputSchema:
+  primary: string
+  fallback: string
+
+outputSchema:
+  fontFamily: string
+  fontFaces: string

package/dist/index.client.d.ts

@@ -0,0 +1,7 @@
+import * as _jay_framework_fullstack_component from '@jay-framework/fullstack-component';
+import { Signals, PageProps } from '@jay-framework/fullstack-component';
+import * as _jay_framework_component from '@jay-framework/component';
+
+declare const designSystemSettingsPage: _jay_framework_fullstack_component.JayStackComponentDefinition<any, any, any, any, [], [Signals<any>, {}], PageProps, {}, _jay_framework_component.JayComponentCore<PageProps, any>>;
+
+export { designSystemSettingsPage };