ShippedMedium

Add a static SynthCSS showcase site (showcase/) with automated GitHub Pages deployment via Actions

Proposed by Jonathan Miller 1 month agoFunding opened 1 month agoFunded 1 month agoShipped 1 month ago
Acceptance · round 1
Shipped
CINo checks
Automated reviewPass with concerns

The PR delivers a complete static showcase covering every spec section. It uses real framework tokens and primitives, scopes all showcase styles to `sc-` classes, and adds a correct GitHub Pages workflow and thorough README docs. A dependency-free checker is wired into `npm test`. No CI ran, so the runtime criteria (no console errors, no overflow at 375px, copy behaviour) rest on the builder's own sandbox browser run. One AI example restates a token value, so a quick manual check is advisable before accepting.

Acceptance criteria · 11 of 13 met
  • UNCLEARshowcase/index.html exists and opens locally with SynthCSS styles applied, with no console errors`showcase/index.html` links `../src/synthcss.css` relatively, and `showcase.js` has no obvious runtime errors; the no-errors claim is backed only by the builder's sandbox browser run, not CI.
  • YESHero contains the project name, tagline, AI-first statement, repo link and docs link`#hero` has `<h1>SynthCSS</h1>`, the exact tagline, the 'Built for AI-generated interfaces' callout, the repo link and the `#readme` docs link.
  • YESThe "Why" section covers the four points concisely`#why` has four `sc-card` list items, one per spec point, each with a one-line paragraph.
  • YESEvery existing token category is visibly rendered using var(--...) from the framework; no hardcoded duplicate token values in showcase.cssThe tokens section renders colors, typography, spacing, radius, shadows, borders, focus, motion and sizing via `var(--…)`. `showcase.css` uses only `var()` values, and `checkShowcaseCss` rejects raw token values and color literals.
  • YESEvery existing layout primitive has a demo, class name, description and HTML snippet`#layouts` has eight `<article>` cards, each with a live demo, a `<code>.name</code>` heading, one sentence and a snippet of 3–5 lines.
  • YESGrid, sidebar, cluster and split each have a width-adjustable demo`#responsive` has four `.sc-frame` frames with `resize: horizontal` plus range inputs wired in `showcase.js`.
  • YESAt least 3 intent-to-SynthCSS examples are present`#ai-examples` has six Intent/SynthCSS pairs, including cluster and grid.
  • YESCopy buttons copy the snippet text`showcase.js` adds a button to each `.sc-code` that copies `code.textContent` via the Clipboard API, falling back to `execCommand`; the browser script verifies this, but only the builder ran it.
  • UNCLEARNo horizontal page overflow at 375px and correct layout at 1280px+`check-showcase-browser.mjs` tests both widths and the builder reports it passing, but nothing was verified in CI.
  • YESNo third-party CSS framework is referencedOnly `../src/synthcss.css` and `showcase.css` are linked, and the checker enforces this with a third-party regex.
  • YESshowcase.css contains only showcase-specific rulesEvery selector in `showcase.css` is scoped to an `sc-` class, with no framework class selectors or custom property definitions.
  • YESA Pages workflow exists, is valid YAML, uses the official Pages actions, and runs on push to main`.github/workflows/pages.yml` uses configure-pages@v5, upload-pages-artifact@v4 and deploy-pages@v4. It sets `pages: write` and `id-token: write`, and triggers on push to main (with the required paths) plus workflow_dispatch.
  • YESshowcase/README.md documents preview, deployment, the manual Pages setting and extension`showcase/README.md` has Local preview, Deployment, One-time setup (Settings → Pages → GitHub Actions) and Adding a section, and is linked from the main `README.md`.
Concerns
  • No CI ran on this commit. The no-console-errors, 375px overflow and copy-button criteria rest only on the builder's sandbox Playwright run, which used a substitute Chromium binary. A maintainer should open the page at 375px and 1280px before merging.
  • The sixth AI example hard-codes `--color-primary: #0b6e4f; --radius-md: 0.5rem;`. The test file implies `0.5rem` is already the real `--radius-md` value, so this 'rounder corners' override changes nothing. It also restates a token value the spec asked not to copy (in `index.html`, not `showcase.css`).
  • Several demos use `--grid-min: 22rem` cards (`#layouts`, `#ai-examples`). Whether these overflow at 375px depends on the framework's `.grid` clamping with `min()`. The diff does not show `layout.css`, so this relies on the builder's browser check.
  • `check-showcase.test.mjs` resolves the repo path with `new URL('..', import.meta.url).pathname`. This breaks on Windows and on paths with URL-encoded characters such as spaces; `fileURLToPath` would be safer.
  • The static checker is regex-based and tied closely to the current markup (exact `<link>` attribute order, `<li class="sc-card`, an exact docs URL). Future harmless edits to the page may trip `npm test`, which now also gates deployment.
CI details
No CI checks ran on this commit.

BackersAccepted
1 accept · 0 rebuild · 0 not voted · quorum 1 of 1
MaintainerMerge

Accepted by the backers and merged by the maintainer.

Ballots · 1
AcceptJonathan Miller

Automated review cost $0.21, counted as builder cost.

Motivation

Give visitors a single static page that shows what SynthCSS is, why it is AI-first, and live demos of its existing tokens and layout primitives. The page is published via GitHub Pages and built with SynthCSS itself.

Scope

Structure

  • Create a new showcase/ directory at the repo root, separate from the framework source.
  • showcase/index.html holds the single page.
  • showcase/showcase.css holds only showcase-specific styles, kept minimal.
  • showcase/showcase.js is optional and holds small vanilla JS.
  • Each section is a self-contained <section id="..."> block so new primitives and components can be added by appending a section. Document this pattern in the README.
  • The page must load the real SynthCSS stylesheet(s) from the repo. Do not copy or recreate token values.
    • Assumption: there is no build step. The workflow copies the framework CSS into the Pages artifact next to the showcase, and links in index.html resolve both locally (relative path) and when deployed.

Sections

  1. Hero
    • Project name.
    • Tagline: "CSS designed to be written by machines and used by humans."
    • Short description.
    • An explicit statement that SynthCSS targets AI-generated interfaces.
    • Link to the GitHub repo (https://github.com/nabledhq/synthcss).
    • Link to documentation. Assumption: the docs link points to the repo's README/docs on GitHub.
  2. Why SynthCSS
    • Four short points, as cards or a list, no long prose:
      • Traditional frameworks are optimized for humans.
      • AI output produces inconsistent CSS.
      • SynthCSS offers a small, semantic, predictable vocabulary.
      • It is designed around model ergonomics.
  3. Design tokens
    • Live swatches and specimens rendered with the actual custom properties for: colors, typography, spacing, radius, shadows, focus states and motion.
    • Only include categories whose tokens exist in the repo. List any missing category in the PR description rather than inventing tokens.
  4. Layouts
    • One example each for .container, .stack, .cluster, .grid, .sidebar, .split, .center and .cover, limited to those that exist.
    • Each example has: a live demo, the class name, a one-sentence description, and a minimal HTML snippet of 15 lines or fewer.
  5. Responsive demos
    • For grid, sidebar, cluster and split, a demo container whose width visitors can change (CSS resize: horizontal or a range input) so they can see:
      • grid columns reduce;
      • sidebar stacks;
      • cluster wraps;
      • split adapts.
  6. AI-friendly examples
    • At least 3 pairs of "Intent" (plain English) and "SynthCSS" (snippet).
    • Include the cluster and grid examples from the proposal.
  7. Code samples (applies site-wide)
    • Snippets are short, use only real SynthCSS classes and tokens, and each has a copy-to-clipboard button.
    • Syntax highlighting only if it can be done without adding a heavy dependency. Assumption: use plain <pre><code> if no highlighter is approved.

Visual style

  • Built primarily with SynthCSS classes and tokens.
  • No Bootstrap, Tailwind, Material UI or similar framework.

Deployment

  • Add .github/workflows/pages.yml using the official actions/configure-pages, actions/upload-pages-artifact and actions/deploy-pages actions.
  • Trigger on push to main (paths: showcase/**, framework CSS, and the workflow file) plus workflow_dispatch.
  • Set the required pages: write and id-token: write permissions.
  • Do not commit generated output.

Documentation

  • Add showcase/README.md, linked from the main README, covering:
    • local preview (open the file or use a simple static server);
    • how deployment works;
    • the one-time manual step: set Settings → Pages → Source to "GitHub Actions";
    • how to add a new section.

Acceptance criteria

  • showcase/index.html exists and opens locally with SynthCSS styles applied, with no console errors.
  • Hero contains the project name, tagline, AI-first statement, repo link and docs link.
  • The "Why" section covers the four points concisely.
  • Every existing token category is visibly rendered using var(--...) from the framework. No hardcoded duplicate token values appear in showcase.css.
  • Every existing layout primitive has a demo, class name, description and HTML snippet.
  • Grid, sidebar, cluster and split each have a width-adjustable demo.
  • At least 3 intent-to-SynthCSS examples are present.
  • Copy buttons copy the snippet text.
  • The page has no horizontal page overflow at a 375px viewport and lays out correctly at 1280px or wider.
  • No third-party CSS framework is referenced.
  • showcase.css contains only showcase-specific rules.
  • A Pages workflow exists, is valid YAML, uses the official Pages actions, and runs on push to main.
  • showcase/README.md documents preview, deployment, the manual Pages setting and extension.

Out of scope

  • New framework components, tokens or primitives.
  • Theming toggles.
  • Static site generators or JS frameworks.
  • Custom domain.
  • Search.
  • Rendering the full docs into the site.
  • Actually enabling Pages in repo settings; a maintainer does this once after merge.

No comments yet.