@spark-line/web-framework 0.1.0

package/skills/spark-line-web-framework/references/qa-checklist.md

@@ -0,0 +1,56 @@
+# Interface QA checklist
+
+## Evidence
+
+- Capture the current rendered baseline before restructuring.
+- Compare against the actual reference at the same viewport.
+- Preserve approved copy, URLs, assets, states, and route behavior.
+
+## Target and neighbors
+
+Verify the changed section, previous section, and next section together:
+
+- independent theme and background;
+- intended seam or separation;
+- no unexplained gap;
+- no accidental overlap;
+- no clipping of focus or content;
+- no cross-section selector effects;
+- correct normal-flow movement after height changes.
+
+## Responsive
+
+Use the project's required viewport matrix. When none exists, include:
+
+- wide desktop;
+- 1024px tablet landscape;
+- 834px tablet portrait;
+- 390px mobile;
+- 320px narrow mobile.
+
+At each width verify:
+
+- no horizontal document overflow;
+- correct DOM and visual order;
+- readable measures and type;
+- minimum 44px interactive targets on touch layouts;
+- visual frames reserve their complete space;
+- component variants reflow without content loss.
+
+## Interaction and accessibility
+
+- Keyboard-operate every control.
+- Keep focus visible.
+- Confirm ARIA labels, relationships, expanded state, and live regions.
+- Confirm Escape and focus return for overlays.
+- Confirm native anchors and history behavior.
+- Confirm reduced motion removes nonessential movement.
+- Confirm React hydration adds behavior without shifting the Astro layout.
+
+## Completion
+
+- Run build and existing tests.
+- Run browser regression tests for unchanged routes.
+- Add or update the component-gallery scenario for every changed reusable
+  component.
+- Report remaining deviations with exact affected viewports and components.

package/skills/spark-line-web-framework/references/stack-boundaries.md

@@ -0,0 +1,53 @@
+# Astro, Sanity, and React boundaries
+
+## Astro
+
+Default to Astro for:
+
+- page and section composition;
+- semantic content markup;
+- surfaces, containers, and spacing;
+- static cards, headings, actions, and disclosures;
+- server or build-time data mapping.
+
+Use slots for open components whose child structure is intentionally flexible.
+Use typed props for closed components with a fixed content contract.
+
+## React islands
+
+Use React only when persistent client state or interaction justifies hydration.
+
+- Keep the Astro-owned section and visual frame outside the island.
+- Accept serializable props.
+- Keep state, effects, and event handling local.
+- Default to `client:visible` or `client:idle`.
+- Use `client:load` only when interaction must work immediately.
+- Support semantic roles, ARIA relationships, keyboard operation, focus return,
+  and reduced motion.
+
+Do not let an island set page-level theme, section padding, container width, or
+adjacent-section layout.
+
+## Sanity
+
+Map Sanity `_type` values to registered Astro section IDs.
+
+Preserve:
+
+- `_key`;
+- record order;
+- Portable Text;
+- references and asset provenance;
+- preview and Stega metadata;
+- the original source record for visual editing.
+
+Expose constrained enums for theme, spacing, and layout. Do not expose arbitrary
+CSS classes or freeform page markup.
+
+Choose unknown-section behavior explicitly:
+
+- `omit` for resilient production rendering;
+- `preserve` for preview tooling and diagnostics;
+- `throw` for strict tests and migrations.
+
+Do not install Sanity into a project that does not use the Sanity export.

package/skills/spark-line-web-framework/scripts/audit_layout.mjs

@@ -0,0 +1,66 @@
+#!/usr/bin/env node
+
+import { readFile, readdir, stat } from "node:fs/promises";
+import path from "node:path";
+import process from "node:process";
+
+const targets = process.argv.slice(2);
+if (targets.length === 0) {
+  console.error("Usage: audit_layout.mjs <file-or-directory> [...]");
+  process.exit(2);
+}
+
+const rules = [
+  {
+    label: "section selector reaches a sibling",
+    expression: /(?:\[data-slf-section\]|\.slf-section|section\.[\w-]+)\s*[+~]/g
+  },
+  {
+    label: "ordinary negative margin",
+    expression: /margin(?:-(?:block|top|bottom))?(?:-start|-end)?:\s*-\d/gi
+  },
+  {
+    label: "raw layout class stored in a Sanity field",
+    expression: /name\s*:\s*["'](?:class|className|cssClass)["']/g
+  }
+];
+
+const files = [];
+for (const target of targets) await collect(path.resolve(target), files);
+
+let findings = 0;
+for (const file of files) {
+  if (!/\.(?:astro|css|js|jsx|mjs|ts|tsx)$/.test(file)) continue;
+  const source = await readFile(file, "utf8");
+  const lines = source.split(/\r?\n/);
+  for (const rule of rules) {
+    rule.expression.lastIndex = 0;
+    for (const match of source.matchAll(rule.expression)) {
+      const line = source.slice(0, match.index).split(/\r?\n/).length;
+      console.log(`${file}:${line}: ${rule.label}`);
+      console.log(`  ${lines[line - 1]?.trim() ?? ""}`);
+      findings += 1;
+    }
+  }
+}
+
+if (findings) {
+  console.log(`Advisory: ${findings} potential framework deviation(s).`);
+  process.exitCode = 1;
+} else {
+  console.log(`No static layout deviations found in ${files.length} file(s).`);
+}
+
+async function collect(target, output) {
+  const details = await stat(target);
+  if (details.isFile()) {
+    output.push(target);
+    return;
+  }
+  for (const entry of await readdir(target, { withFileTypes: true })) {
+    if (["node_modules", "dist", ".git"].includes(entry.name)) continue;
+    const next = path.join(target, entry.name);
+    if (entry.isDirectory()) await collect(next, output);
+    else output.push(next);
+  }
+}

package/src/astro/Action.astro

@@ -0,0 +1,34 @@
+---
+import type { HTMLAttributes } from "astro/types";
+
+type AnchorAttributes = HTMLAttributes<"a">;
+type ButtonAttributes = HTMLAttributes<"button">;
+
+interface Props extends AnchorAttributes, ButtonAttributes {
+  href?: string;
+  variant?: "primary" | "secondary" | "quiet";
+  size?: "sm" | "md" | "lg";
+  type?: "button" | "submit" | "reset";
+}
+
+const {
+  href,
+  variant = "primary",
+  size = "md",
+  type = "button",
+  class: className,
+  ...attributes
+} = Astro.props;
+const Tag = href ? "a" : "button";
+---
+
+<Tag
+  class:list={["slf-action", className]}
+  data-variant={variant}
+  data-size={size}
+  href={href}
+  type={href ? undefined : type}
+  {...attributes}
+>
+  <slot />
+</Tag>

package/src/astro/CardShell.astro

@@ -0,0 +1,19 @@
+---
+import type { HTMLAttributes } from "astro/types";
+
+interface Props extends HTMLAttributes<"article"> {
+  as?: "article" | "div" | "li";
+  surface?: "default" | "quiet" | "accent";
+}
+
+const {
+  as: Tag = "article",
+  surface = "default",
+  class: className,
+  ...attributes
+} = Astro.props;
+---
+
+<Tag class:list={["slf-card-shell", className]} data-surface={surface} {...attributes}>
+  <slot />
+</Tag>

package/src/astro/Cluster.astro

@@ -0,0 +1,30 @@
+---
+import type { HTMLAttributes } from "astro/types";
+import type { LayoutGap } from "./Stack.astro";
+
+interface Props extends HTMLAttributes<"div"> {
+  as?: "div" | "nav" | "ul";
+  gap?: LayoutGap;
+  align?: "start" | "center" | "end" | "stretch";
+  justify?: "start" | "center" | "end" | "between";
+}
+
+const {
+  as: Tag = "div",
+  gap = "sm",
+  align = "center",
+  justify = "start",
+  class: className,
+  ...attributes
+} = Astro.props;
+---
+
+<Tag
+  class:list={["slf-cluster", className]}
+  data-gap={gap}
+  data-align={align}
+  data-justify={justify}
+  {...attributes}
+>
+  <slot />
+</Tag>

package/src/astro/Container.astro

@@ -0,0 +1,15 @@
+---
+import type { HTMLAttributes } from "astro/types";
+import type { ContainerWidth } from "./Section.astro";
+
+interface Props extends HTMLAttributes<"div"> {
+  as?: "div" | "article" | "nav";
+  width?: ContainerWidth;
+}
+
+const { as: Tag = "div", width = "wide", class: className, ...attributes } = Astro.props;
+---
+
+<Tag class:list={["slf-container", className]} data-container={width} {...attributes}>
+  <slot />
+</Tag>

package/src/astro/Disclosure.astro

@@ -0,0 +1,16 @@
+---
+import type { HTMLAttributes } from "astro/types";
+
+interface Props extends HTMLAttributes<"details"> {
+  summary: string;
+}
+
+const { summary, class: className, ...attributes } = Astro.props;
+---
+
+<details class:list={["slf-disclosure", className]} {...attributes}>
+  <summary>{summary}</summary>
+  <div class="slf-disclosure__content">
+    <slot />
+  </div>
+</details>

package/src/astro/Grid.astro

@@ -0,0 +1,38 @@
+---
+import type { HTMLAttributes } from "astro/types";
+import type { LayoutGap } from "./Stack.astro";
+
+interface Props extends HTMLAttributes<"div"> {
+  as?: "div" | "ul" | "ol";
+  columns?: 1 | 2 | 3 | 4 | 6 | 12 | "auto-fit" | "auto-fill";
+  minItemWidth?: string;
+  gap?: LayoutGap;
+}
+
+const {
+  as: Tag = "div",
+  columns = "auto-fit",
+  minItemWidth = "16rem",
+  gap = "md",
+  class: className,
+  style,
+  ...attributes
+} = Astro.props;
+const inlineStyle = [
+  `--slf-grid-min:${minItemWidth}`,
+  typeof columns === "number" ? `--slf-grid-columns:${columns}` : "",
+  typeof style === "string" ? style : ""
+]
+  .filter(Boolean)
+  .join(";");
+---
+
+<Tag
+  class:list={["slf-grid", className]}
+  data-columns={columns}
+  data-gap={gap}
+  style={inlineStyle}
+  {...attributes}
+>
+  <slot />
+</Tag>

package/src/astro/Heading.astro

@@ -0,0 +1,17 @@
+---
+import type { HTMLAttributes } from "astro/types";
+
+export type HeadingSize = "display" | "h1" | "h2" | "h3" | "h4" | "h5" | "h6";
+
+interface Props extends HTMLAttributes<"h2"> {
+  level?: 1 | 2 | 3 | 4 | 5 | 6;
+  size?: HeadingSize;
+}
+
+const { level = 2, size = `h${level}` as HeadingSize, class: className, ...attributes } = Astro.props;
+const Tag = `h${level}` as const;
+---
+
+<Tag class:list={["slf-heading", className]} data-size={size} {...attributes}>
+  <slot />
+</Tag>

package/src/astro/PageFlow.astro

@@ -0,0 +1,13 @@
+---
+import type { HTMLAttributes } from "astro/types";
+
+interface Props extends HTMLAttributes<"main"> {
+  as?: "main" | "div";
+}
+
+const { as: Tag = "main", class: className, ...attributes } = Astro.props;
+---
+
+<Tag class:list={["slf-page-flow", className]} data-slf-page-flow {...attributes}>
+  <slot />
+</Tag>

package/src/astro/Section.astro

@@ -0,0 +1,44 @@
+---
+import type { HTMLAttributes } from "astro/types";
+
+export type SectionTheme = "default" | "inverse" | "accent" | "quiet";
+export type SectionSpace = "none" | "xs" | "sm" | "md" | "lg" | "xl";
+export type ContainerWidth = "narrow" | "content" | "wide" | "full";
+
+interface Props extends HTMLAttributes<"section"> {
+  as?: "section" | "header" | "footer" | "aside" | "div";
+  theme?: SectionTheme;
+  spaceTop?: SectionSpace;
+  spaceBottom?: SectionSpace;
+  container?: ContainerWidth | false;
+}
+
+const {
+  as: Tag = "section",
+  theme = "default",
+  spaceTop = "md",
+  spaceBottom = "md",
+  container = "wide",
+  class: className,
+  ...attributes
+} = Astro.props;
+---
+
+<Tag
+  class:list={["slf-section", className]}
+  data-slf-section
+  data-theme={theme}
+  data-space-top={spaceTop}
+  data-space-bottom={spaceBottom}
+  {...attributes}
+>
+  {
+    container === false ? (
+      <slot />
+    ) : (
+      <div class="slf-container" data-container={container}>
+        <slot />
+      </div>
+    )
+  }
+</Tag>

package/src/astro/SectionGroup.astro

@@ -0,0 +1,14 @@
+---
+import type { HTMLAttributes } from "astro/types";
+
+interface Props extends HTMLAttributes<"div"> {
+  as?: "div" | "section";
+  mode?: "joined" | "overlap";
+}
+
+const { as: Tag = "div", mode = "joined", class: className, ...attributes } = Astro.props;
+---
+
+<Tag class:list={["slf-section-group", className]} data-slf-section-group data-mode={mode} {...attributes}>
+  <slot />
+</Tag>

package/src/astro/Stack.astro

@@ -0,0 +1,16 @@
+---
+import type { HTMLAttributes } from "astro/types";
+
+export type LayoutGap = "none" | "xs" | "sm" | "md" | "lg" | "xl";
+
+interface Props extends HTMLAttributes<"div"> {
+  as?: "div" | "section" | "article" | "ul" | "ol";
+  gap?: LayoutGap;
+}
+
+const { as: Tag = "div", gap = "md", class: className, ...attributes } = Astro.props;
+---
+
+<Tag class:list={["slf-stack", className]} data-gap={gap} {...attributes}>
+  <slot />
+</Tag>

package/src/astro/Text.astro

@@ -0,0 +1,21 @@
+---
+import type { HTMLAttributes } from "astro/types";
+
+interface Props extends HTMLAttributes<"p"> {
+  as?: "p" | "span" | "div" | "li";
+  size?: "small" | "body" | "lead";
+  tone?: "default" | "muted";
+}
+
+const {
+  as: Tag = "p",
+  size = "body",
+  tone = "default",
+  class: className,
+  ...attributes
+} = Astro.props;
+---
+
+<Tag class:list={["slf-text", className]} data-size={size} data-tone={tone} {...attributes}>
+  <slot />
+</Tag>

package/src/astro/VisualFrame.astro

@@ -0,0 +1,32 @@
+---
+import type { HTMLAttributes } from "astro/types";
+
+interface Props extends HTMLAttributes<"div"> {
+  as?: "div" | "figure";
+  aspectRatio?: string;
+  minBlockSize?: string;
+  overflow?: "clip" | "hidden" | "visible";
+}
+
+const {
+  as: Tag = "div",
+  aspectRatio,
+  minBlockSize,
+  overflow = "clip",
+  class: className,
+  style,
+  ...attributes
+} = Astro.props;
+const inlineStyle = [
+  aspectRatio ? `--slf-visual-aspect:${aspectRatio}` : "",
+  minBlockSize ? `--slf-visual-min-block:${minBlockSize}` : "",
+  `--slf-visual-overflow:${overflow}`,
+  typeof style === "string" ? style : ""
+]
+  .filter(Boolean)
+  .join(";");
+---
+
+<Tag class:list={["slf-visual-frame", className]} data-slf-visual-frame style={inlineStyle} {...attributes}>
+  <slot />
+</Tag>

package/src/astro/index.d.ts

@@ -0,0 +1,17 @@
+export { default as PageFlow } from "./PageFlow.astro";
+export { default as Section } from "./Section.astro";
+export { default as SectionGroup } from "./SectionGroup.astro";
+export { default as Container } from "./Container.astro";
+export { default as Stack } from "./Stack.astro";
+export { default as Cluster } from "./Cluster.astro";
+export { default as Grid } from "./Grid.astro";
+export { default as VisualFrame } from "./VisualFrame.astro";
+export { default as Heading } from "./Heading.astro";
+export { default as Text } from "./Text.astro";
+export { default as Action } from "./Action.astro";
+export { default as CardShell } from "./CardShell.astro";
+export { default as Disclosure } from "./Disclosure.astro";
+
+export type { ContainerWidth, SectionSpace, SectionTheme } from "./Section.astro";
+export type { LayoutGap } from "./Stack.astro";
+export type { HeadingSize } from "./Heading.astro";

package/starter/astro/astro.config.mjs

@@ -0,0 +1,5 @@
+import { defineConfig } from "astro/config";
+
+export default defineConfig({
+  output: "static"
+});

package/starter/astro/package.json

@@ -0,0 +1,13 @@
+{
+  "name": "spark-line-framework-starter",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "astro dev",
+    "build": "astro build"
+  },
+  "dependencies": {
+    "@spark-line/web-framework": "0.1.0",
+    "astro": "^7.0.3"
+  }
+}

package/starter/astro/src/pages/index.astro

@@ -0,0 +1,48 @@
+---
+import "@spark-line/web-framework/styles/foundation.css";
+import "../styles/project.css";
+import {
+  Action,
+  CardShell,
+  Grid,
+  Heading,
+  PageFlow,
+  Section,
+  Stack,
+  Text,
+  VisualFrame
+} from "@spark-line/web-framework/astro";
+---
+
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width" />
+    <title>Spark Line framework starter</title>
+  </head>
+  <body>
+    <PageFlow>
+      <Section theme="default" spaceTop="xl" spaceBottom="lg">
+        <Stack gap="md">
+          <Heading level={1} size="display">Structure without visual inheritance</Heading>
+          <Text size="lead">Supply the project's reviewed tokens and content.</Text>
+          <Action href="#proof">See the proof</Action>
+        </Stack>
+      </Section>
+      <Section id="proof" theme="quiet" spaceTop="lg" spaceBottom="xl">
+        <Grid columns="auto-fit" minItemWidth="15rem">
+          <CardShell>
+            <Stack gap="sm">
+              <Heading level={2} size="h4">Section-owned edges</Heading>
+              <Text>Changing this card cannot restyle the following section.</Text>
+            </Stack>
+          </CardShell>
+          <VisualFrame aspectRatio="4 / 3" class="starter-frame">
+            <Text>Reserved visual space</Text>
+          </VisualFrame>
+        </Grid>
+      </Section>
+    </PageFlow>
+  </body>
+</html>

package/starter/astro/src/pages/style-guide.astro

@@ -0,0 +1,76 @@
+---
+import "@spark-line/web-framework/styles/foundation.css";
+import "../styles/project.css";
+import {
+  Action,
+  CardShell,
+  Cluster,
+  Disclosure,
+  Grid,
+  Heading,
+  PageFlow,
+  Section,
+  SectionGroup,
+  Stack,
+  Text,
+  VisualFrame
+} from "@spark-line/web-framework/astro";
+---
+
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width" />
+    <meta name="robots" content="noindex, nofollow" />
+    <title>Component gallery</title>
+  </head>
+  <body>
+    <PageFlow>
+      <Section theme="default" spaceTop="lg" spaceBottom="lg">
+        <Stack gap="md">
+          <Text size="small">Unlinked development route</Text>
+          <Heading level={1} size="display">Component gallery</Heading>
+          <Text size="lead">Every registered variant and meaningful state belongs here.</Text>
+        </Stack>
+      </Section>
+
+      <SectionGroup mode="joined">
+        <Section theme="quiet" spaceTop="lg" spaceBottom="lg">
+          <Stack gap="md">
+            <Heading level={2} size="h2">Actions and surfaces</Heading>
+            <Cluster>
+              <Action href="#layout">Primary</Action>
+              <Action href="#layout" variant="secondary">Secondary</Action>
+              <Action href="#layout" variant="quiet">Quiet</Action>
+            </Cluster>
+            <Grid columns="auto-fit" minItemWidth="14rem">
+              {
+                ["default", "quiet", "accent"].map((surface) => (
+                  <CardShell surface={surface}>
+                    <Heading level={3} size="h4">{surface}</Heading>
+                    <Text>Project tokens supply this surface.</Text>
+                  </CardShell>
+                ))
+              }
+            </Grid>
+          </Stack>
+        </Section>
+
+        <Section id="layout" theme="default" spaceTop="lg" spaceBottom="lg">
+          <Grid columns={2}>
+            <Stack gap="sm">
+              <Heading level={2} size="h3">Native disclosure</Heading>
+              <Disclosure summary="What owns section spacing?">
+                <Text>The section owns both internal vertical edges.</Text>
+              </Disclosure>
+            </Stack>
+            <VisualFrame aspectRatio="16 / 9" class="starter-frame">
+              <Text>16 / 9 reserved frame</Text>
+            </VisualFrame>
+          </Grid>
+        </Section>
+      </SectionGroup>
+    </PageFlow>
+  </body>
+</html>