feat: visual regression + gallery marketing polish

.github/workflows/ci.yml

@@ -34,3 +34,12 @@ jobs:
 
       - name: Pack dry-run
         run: npm run pack:check
+
+      - name: Install Playwright Chromium
+        run: npx playwright install --with-deps chromium
+
+      # Baselines may be OS-sensitive (fonts). Failures are reported but do not block merge;
+      # re-baseline with: npm run build && npm run test:visual:update
+      - name: Visual regression (gallery)
+        continue-on-error: true
+        run: npm run test:visual

.gitignore

@@ -32,5 +32,11 @@ next-env.d.ts
 # local QA / scratch
 .tmp-shots
 
+# Playwright
+/test-results/
+/playwright-report/
+/blob-report/
+/playwright/.cache/
+
 # registry generated (optional later)
 # registry/dist

.npmrc

@@ -0,0 +1 @@
+legacy-peer-deps=true

CHANGELOG.md

@@ -10,6 +10,9 @@ Versioning follows [SemVer](https://semver.org/).
 ### Added
 
 - Theme Builder **shareable URL**: `#theme?lang=aurora&a=7c3aed&…` + **Copy share link**
+- **Visual regression** — Playwright gallery screenshots (`npm run test:visual`) + CI step
+- Gallery **Welcome** feature cards (Theme Builder + App shell) · README gallery map
+- GETTING-STARTED refresh for v1.8 languages + gallery hashes
 
 ## [1.8.0] — 2026-07-31
 

README.md

@@ -62,6 +62,22 @@ Full walkthrough: [docs/GETTING-STARTED.md](./docs/GETTING-STARTED.md)
 - [`@softglass/tokens`](https://www.npmjs.com/package/@softglass/tokens) · [`@softglass/ui`](https://www.npmjs.com/package/@softglass/ui)
 - Repo: [github.com/ArdaDDemir/softglass](https://github.com/ArdaDDemir/softglass) · tag `v1.8.0`
 
+### Softglass Gallery (local tour)
+
+```bash
+npm run dev
+# open http://localhost:3000
+```
+
+| Hash | What you get |
+| --- | --- |
+| `#welcome` | Pitch + shortcuts |
+| `#install` | Consumer install steps |
+| `#languages` | Six dialects |
+| `#theme` | **Theme Builder** — brand lab · share URL · copy CSS |
+| `#app` | Mini product shell · DataTable inventory |
+| `#library` / `#library/button` | Component Studio (every export) |
+
 ### Brand override (colors only)
 
 ```css
@@ -71,6 +87,8 @@ Full walkthrough: [docs/GETTING-STARTED.md](./docs/GETTING-STARTED.md)
 }
 ```
 
+Or use the gallery **Theme Builder** and paste the exported CSS.
+
 ## Why Softglass exists
 
 Most projects need the **same soft UI grammar** (rounded, glossy, translucent, calm) but not the **same colors**. Softglass separates:

apps/web/e2e/gallery.visual.spec.ts

@@ -0,0 +1,48 @@
+import { expect, test } from "@playwright/test";
+
+/**
+ * Gallery page visual smoke — aurora language, reduced motion.
+ * Hash routes: welcome · theme · app · library/button · library/datatable
+ */
+
+const PAGES: { name: string; hash: string }[] = [
+  { name: "welcome", hash: "#welcome" },
+  { name: "theme", hash: "#theme" },
+  { name: "app", hash: "#app" },
+  { name: "library-button", hash: "#library/button" },
+  { name: "library-datatable", hash: "#library/datatable" },
+];
+
+test.beforeEach(async ({ page }) => {
+  // Stable language for snapshots
+  await page.addInitScript(() => {
+    try {
+      localStorage.setItem("softglass-theme", "aurora");
+    } catch {
+      /* ignore */
+    }
+  });
+});
+
+for (const { name, hash } of PAGES) {
+  test(`gallery ${name}`, async ({ page }) => {
+    await page.goto(`/${hash}`, { waitUntil: "networkidle" });
+    // Let client hash routing + theme paint settle
+    await page.waitForTimeout(500);
+    await expect(page.locator(".sg-gallery")).toBeVisible();
+
+    // Hide sticky gallery chrome that can shimmer (blur) across runs
+    await page.addStyleTag({
+      content: `
+        .sg-gallery-top, .sg-gallery-bottom {
+          backdrop-filter: none !important;
+          -webkit-backdrop-filter: none !important;
+        }
+      `,
+    });
+
+    await expect(page).toHaveScreenshot(`${name}.png`, {
+      fullPage: true,
+    });
+  });
+}

apps/web/src/app/globals.css

@@ -314,7 +314,23 @@ body {
   align-items: center;
 }
 
-/* Welcome → Theme Builder CTA */
+/* Welcome feature cards */
+.sg-welcome-feature-grid {
+  display: grid;
+  gap: 1rem;
+  grid-template-columns: minmax(0, 1fr);
+}
+
+@media (min-width: 720px) {
+  .sg-welcome-feature-grid {
+    grid-template-columns: minmax(0, 1fr) minmax(0, 1fr);
+  }
+}
+
+.sg-welcome-feature-grid > * {
+  min-width: 0;
+}
+
 .sg-welcome-theme-cta {
   border-color: color-mix(in srgb, var(--sg-accent) 28%, var(--sg-border-frost));
   box-shadow:

apps/web/src/components/playground/pages.tsx

@@ -108,15 +108,15 @@ function WelcomePage({ onGo }: { onGo: (id: GalleryPageId) => void }) {
       <Card surface="glass" as="section" hoverable>
         <CardHeader>
           <Badge variant="solid" size="sm">
-            open design system
+            open design system · v1.8
           </Badge>
           <CardTitle className="sg-gallery-hero-title">
             Soft glass UI. You own the code.
           </CardTitle>
           <CardDescription className="sg-gallery-hero-desc">
             Softglass is a kit of tokens + React components for Next.js. Six
-            languages (three dark), recolor the brand, compose product screens —
-            MIT, shadcn-style ownership.
+            languages, live Theme Builder, product App shell, and a Component
+            Studio for every export — MIT, shadcn-style ownership.
           </CardDescription>
         </CardHeader>
         <CardFooter className="sg-gallery-chip-row">
@@ -148,26 +148,51 @@ function WelcomePage({ onGo }: { onGo: (id: GalleryPageId) => void }) {
         ))}
       </div>
 
-      <Card surface="solid" as="section" className="sg-welcome-theme-cta">
-        <CardHeader>
-          <Badge size="sm" variant="accent" look="soft">
-            new · 1.8
-          </Badge>
-          <CardTitle>Theme Builder</CardTitle>
-          <CardDescription>
-            Language is the Softglass dialect. Brand is your accent. Recolor live,
-            preview components, copy the CSS override — no Storybook, no SaaS.
-          </CardDescription>
-        </CardHeader>
-        <CardFooter className="sg-gallery-chip-row">
-          <Button variant="primary" onClick={() => onGo("theme")}>
-            Open Theme Builder
-          </Button>
-          <Button variant="secondary" size="sm" onClick={() => onGo("languages")}>
-            Pick a language first
-          </Button>
-        </CardFooter>
-      </Card>
+      <div className="sg-welcome-feature-grid">
+        <Card surface="solid" as="section" className="sg-welcome-theme-cta">
+          <CardHeader>
+            <Badge size="sm" variant="accent" look="soft">
+              brand
+            </Badge>
+            <CardTitle>Theme Builder</CardTitle>
+            <CardDescription>
+              Language is the dialect. Brand is your accent. Recolor live, copy
+              CSS, or share a{" "}
+              <code style={{ fontSize: "0.9em" }}>#theme?…</code> link.
+            </CardDescription>
+          </CardHeader>
+          <CardFooter className="sg-gallery-chip-row">
+            <Button variant="primary" size="sm" onClick={() => onGo("theme")}>
+              Open Theme Builder
+            </Button>
+          </CardFooter>
+        </Card>
+
+        <Card surface="solid" as="section">
+          <CardHeader>
+            <Badge size="sm" variant="solid" look="soft">
+              product
+            </Badge>
+            <CardTitle>App shell</CardTitle>
+            <CardDescription>
+              Mini inventory product: AppShell · DataTable · settings · command
+              palette — one working screen, not loose demos.
+            </CardDescription>
+          </CardHeader>
+          <CardFooter className="sg-gallery-chip-row">
+            <Button variant="primary" size="sm" onClick={() => onGo("app")}>
+              Open App
+            </Button>
+            <Button
+              variant="secondary"
+              size="sm"
+              onClick={() => onGo("library")}
+            >
+              Component Studio
+            </Button>
+          </CardFooter>
+        </Card>
+      </div>
 
       <Card surface="solid" as="section">
         <CardHeader>
@@ -201,8 +226,8 @@ function WelcomePage({ onGo }: { onGo: (id: GalleryPageId) => void }) {
       </Card>
 
       <Alert variant="info" title="Not a Storybook farm">
-        This is a product-facing tour of Softglass — real components, one page at
-        a time, so the kit stays fast on phones.
+        Product-facing Softglass tour — real components, one page at a time,
+        phone-friendly. Install from npm when you are ready to ship.
       </Alert>
     </div>
   );

docs/GETTING-STARTED.md

@@ -2,7 +2,7 @@
 
 Three steps to use Softglass in a **Next.js App Router** app.
 
-> Published packages: `@softglass/tokens` + `@softglass/ui` (current **1.4.0**).  
+> Published packages: `@softglass/tokens` + `@softglass/ui` (current **1.8.0**).  
 > Local monorepo: `npm run build:ui` then `npm run dev`. Dry-run tarballs: `npm run pack:check`.
 
 ---
@@ -13,16 +13,26 @@ Three steps to use Softglass in a **Next.js App Router** app.
 npm install @softglass/tokens @softglass/ui
 ```
 
-Peer deps: `react` and `react-dom` ≥ 18. UI also peers `@softglass/tokens` **^1.4.0** (import styles from tokens).
+Peer deps: `react` and `react-dom` ≥ 18. UI also peers `@softglass/tokens` **^1.8.0** (import styles from tokens).
 
 ### Local monorepo (this repo)
 
 ```bash
 npm install
 npm run build:ui   # builds packages/ui → dist
-npm run dev        # playground at http://localhost:3000
+npm run dev        # Softglass Gallery at http://localhost:3000
 ```
 
+Gallery highlights:
+
+| Hash | Page |
+| --- | --- |
+| `#theme` | Theme Builder (brand lab + share URL) |
+| `#app` | Mini product shell + DataTable |
+| `#library/button` | Component Studio |
+
+Visual regression (after build): `npm run test:visual` · update baselines: `npm run test:visual:update`
+
 ### Local tarball dry-run (before npm publish)
 
 ```bash
@@ -54,7 +64,7 @@ export default function RootLayout({ children }: { children: React.ReactNode })
 }
 ```
 
-Languages: `aurora` | `obsidian` | `mist` | `pearl`
+Languages: `aurora` | `mist` | `pearl` | `obsidian` | `noir` | `ember`
 
 ### Brand colors only
 

docs/claude/todos.md

@@ -1,62 +1,44 @@
 # Softglass — TODO
 
-> **v1.0–v1.8.0:** shipped (npm + tag) · plan: [v1.8-plan.md](./v1.8-plan.md)  
-> Arşiv: [v1.7-plan.md](./v1.7-plan.md) · [v1.6-plan.md](./v1.6-plan.md)  
-> **Hesap:** gh **ArdaDDemir** · npm **ardaddemir** · work/Feedemy **YASAK**.  
-> **Kural:** Aynı anda tek sprint · otomatik push yok.
+> **v1.0–v1.8.0:** shipped · **Sıradaki:** visual + marketing (1.9 prep)  
+> Plan arşiv: [v1.8-plan.md](./v1.8-plan.md) · [v1.7-plan.md](./v1.7-plan.md)  
+> **Hesap:** gh **ArdaDDemir** · npm **ardaddemir** · work/Feedemy **YASAK**.
 
 ---
 
 ## Şu an durum
 
 | Sürüm | Durum |
 |-------|--------|
-| 1.0.0 – 1.8.0 | **shipped** (npm + tag) |
-| 1.9+ | Marketing polish / visual / token JSON |
+| 1.0.0 – 1.8.0 | **shipped** |
+| **1.9 prep** | share URL done · visual regression · marketing polish |
 
-**Repo:** https://github.com/ArdaDDemir/softglass  
-**npm:** `@softglass/tokens@1.8.0` · `@softglass/ui@1.8.0`  
-**Tag:** `v1.8.0`
+**npm:** `@softglass/tokens@1.8.0` · `@softglass/ui@1.8.0` · tag `v1.8.0`
 
 ---
 
-## v1.7 — bitti
+## Done recently
 
-- [x] DataTable + virtualization + Studio + App recipe  
-- [x] 1.7.0 publish + tag + PR #9 → main  
+- [x] Theme share URL (`#theme?…`) — PR #12  
+- [x] Visual regression (Playwright gallery snapshots + CI)  
+- [x] Marketing polish (Welcome cards · README gallery · GETTING-STARTED)  
 
 ---
 
-## v1.8 — Theme Builder — bitti
+## v1.9+ backlog (kalan)
 
-- [x] `#theme` brand lab · export CSS · Apply / Reset · draft  
-- [x] Welcome CTA  
-- [x] `#app` mini product shell (inventory · settings · palette)  
-- [x] Layout polish (brand colors fit)  
-- [x] 1.8.0 publish + tag + PR → main  
-
-### Optional leftover
-
-- [x] Shareable hash/query for brand draft (`#theme?lang=…&a=…` + Copy share link)
-
----
-
-## v1.9+ backlog
-
-- [ ] Docs marketing site polish  
-- [ ] Visual regression  
 - [ ] Token JSON / Figma bridge  
 - [ ] i18n / RTL  
 - [ ] Full calendar / TimePicker suite  
 - [ ] DatePicker Calendar extract  
+- [ ] (optional) expand visual baselines / mobile project  
 
 ---
 
 ## Yeni session
 
 ```text
-Softglass v1.8.0 shipped — Theme Builder + App shell
-npm @softglass/tokens@1.8.0 · @softglass/ui@1.8.0 · tag v1.8.0
-Next: 1.9+ backlog
+Softglass — after 1.9 visual+marketing
+Next: calendar/TimePicker or token JSON
 work hesabına push yok
 ```