Atelier-Kit

Atelier-Kit is a lightweight configurable showcase kit for makers, artists, artisans and small creative activities.

It is designed for people who want a clean online catalog for handmade items without starting a full e-commerce project.

Core idea

Configure the site, add items and images, deploy the showcase.

No cart. No checkout. No accounts. No public comments. No contact-form swamp.

Studio — local authoring

Atelier-Kit includes Studio, a browser-based editor for the whole site — no YAML by hand, no WordPress, no database.

From the project folder:

npm run studio

Opens http://127.0.0.1:5173/studio on localhost only. Studio writes directly to config/, content/ and item images on disk.

What you can edit in Studio

• Site identity, appearance, layout, hero, footer, contact and social links
• Catalog items (with photo upload), collections, news, Signal Clouds and public FAQ answers
• About page and publish readiness (Content Doctor + Put site online)

Production stays read-only — /studio is disabled on Vercel. Clients use Atelier Desktop (Tauri) for the same UI without exposing authoring on the live URL.

→ Full guide: docs/usage/studio.md · Desktop: desktop/README.md

Features

• SvelteKit application.
• Vercel-ready deployment.
• YAML-driven site identity.
• YAML-driven catalog settings.
• YAML-driven item/card content.
• File-based item/card CRUD.
• Nested item meta information.
• Static images.
• Configurable Signal Clouds.
• Single-choice Signal Cloud answers.
• Browser-local Signal Cloud selections.
• Copyable Visitor Brief generated from Signal Cloud selections.
• Public /faq page projected from selected Signal Cloud records.
• Conditional FAQ navigation and schema.org FAQPage JSON-LD.
• Placeholder image for quick setup.
• Content validation script.
• Content Doctor pre-publish warnings.
• Local studio for browser-based editing (npm run studio).
• Item photo upload in studio with automatic image paths.
• About page (config/about.yaml, /about).
• Publish prep script (npm run publish).
• Client site scaffolds and guided site:wizard.
• Client site upgrade command (npm run site:upgrade).
• Configurable site appearance from studio.
• Item meta presets for common creative showcase types.
• Micro-CMS discovery: XML sitemap (/sitemap.xml), robots.txt, RSS feed (/news/rss.xml), client-side search on items and news.
• Structured data: JSON-LD on news, about and eligible FAQ pages.
• Atelier Desktop (Tauri) for client authoring without exposing /studio on production (ADR 0007).
• Put site online — one-click publish from /studio/readiness without terminal commands for the client.

Current release

Latest release: v0.1.20 — Micro-CMS Tier 1 and Tier 2 (sitemap, RSS, search, JSON-LD, Desktop authoring, guided publish).

See GitHub Releases for highlights and validation notes.

Quick start

Install dependencies:

npm install

Run the development server:

npm run dev

Create a first item:

npm run item:new -- my-first-item "My First Item"

Validate content and build:

npm run item:validate
npm run check
npm run build

Preview the site locally:

npm run preview

Open Studio (local authoring UI):

npm run studio

First customization path

For a first real setup, edit files in this order:

1. config/site.yaml for site name, tagline and footer text.
2. config/catalog.yaml for catalog field visibility and item vocabulary.
3. config/signal-clouds.yaml for lightweight visitor preference questions.
4. content/items/ for item records.
5. static/images/items/ for item images.

The fastest useful path is:

npm run item:new -- ceramic-bowl "Ceramic Bowl"
npm run item:list
npm run item:validate
npm run dev

Then edit:

content/items/ceramic-bowl.yaml

Item/Card CRUD

Atelier-Kit 1.0 uses file-based CRUD.

Helper commands:

npm run item:new -- my-first-item "My First Item"
npm run item:list
npm run item:validate

• Create: run npm run item:new -- <id> "<Title>", then edit the generated YAML file.
• Read: the homepage and /items/<id> pages are generated automatically.
• Update: edit the YAML file or replace the image.
• Delete: remove the YAML file and optionally remove the image.
• Validate: run npm run item:validate.

This keeps the template simple and avoids database, login and admin-dashboard complexity.

Item relationships

Item YAML can optionally describe ordered, typed relationships to other item ids:

relations:
  - type: "inspired-by"
    target: "earlier-work"
    label: "Earlier study"
  - type: "part-of"
    target: "summer-project"

type and target are required non-empty strings; label is an optional display label. Values are trimmed while loading, and a blank label is omitted. Item records without relations remain compatible and load with relations: [].

Relationship types are open and domain-neutral, not a fixed vocabulary. Validation requires targets to exist, rejects self-references by default, and rejects repeated edges with the same trimmed type and target (labels do not make an edge unique). Cycles between different items and one-way relationships remain valid.

Nested meta information

Item detail pages can render configurable meta information from each item YAML file.

Example:

meta:
  - label: "Material"
    value: "Ceramic"

  - label: "Object details"
    children:
      - label: "Finish"
        value: "Matte glaze"
      - label: "Care"
        value: "Dust gently"

Meta entries support:

• label;
• optional value;
• optional children.

Use nested children for simple submeta structures. Keep nesting shallow unless there is a clear reason.

Signal Clouds

Signal Clouds are configurable word-cloud-style questions shown on item pages.

They let visitors express a lightweight preference or perception without accounts, comments, names or email addresses.

Rules:

• one cloud represents one question;
• each cloud is always single-choice;
• visitors may change their answer;
• changing an answer replaces the previous local selection;
• multiple-choice clouds are intentionally out of scope;
• no public counters are shown;
• no personal data is collected.

Public FAQ

A Signal Cloud can optionally publish an official editorial answer on /faq.

The FAQ is configured inside the same record in config/signal-clouds.yaml; there is no separate FAQ content file.

A record appears publicly only when the cloud is enabled, faq.visible is true, and both the shared question and faq.answer are non-empty. Optional faq.group and non-negative faq.order values control presentation.

When at least one eligible entry exists, Atelier-Kit adds the FAQ link to public navigation and emits schema.org FAQPage JSON-LD. Otherwise /faq shows an empty state and the navigation link stays hidden.

FAQ publishing is purely editorial: there is no visitor submission endpoint, inbox, moderation queue or stored message.

Visitor Brief

Visitor Brief turns Signal Cloud selections into a short copyable plain-text note.

A visitor can select impressions on an item page, copy the generated brief and paste it into email, WhatsApp, Instagram, Signal or another external contact channel.

No account, textarea, form backend, database or server-side storage is required.

Project structure

• config/site.yaml configures the site identity.
• config/catalog.yaml configures catalog vocabulary and visible fields.
• config/signal-clouds.yaml configures Signal Cloud questions and answers.
• content/items/ contains item records.
• static/images/items/ contains item images.
• docs/ contains product, architecture and usage notes.
• src/ contains the SvelteKit application.

Development

Run all checks before pushing:

npm run item:validate
npm run check
npm run build

The repository also includes a GitHub Actions workflow that runs validation on pushes and pull requests.

Content Doctor

Atelier-Kit includes a non-fatal pre-publish doctor.

The validator checks structural correctness:

npm run content:validate

The doctor checks publishing readiness:

npm run content:doctor

It warns about starter/demo content such as placeholder images, Replace with text, demo notices, test item ids and placeholder contact addresses.

Use strict mode when you want warnings to fail the command:

npm run content:doctor -- --strict

Deploy

Atelier-Kit uses the Vercel adapter.

Deploy with:

npx vercel

Production deploy:

npx vercel --prod

See docs/usage/deploy-vercel.md for the pre-deploy checklist.

Documentation

• docs/usage/configuration.md explains the YAML configuration files.
• docs/usage/customization.md explains the first customization workflow.
• docs/usage/editorial-markup.md explains Atelier Mark inline text emphasis.
• docs/usage/deploy-vercel.md explains Vercel deployment.
• docs/usage/contact-flow.md explains the no-textarea contact flow.
• docs/usage/content-doctor.md explains pre-publish checks.
• docs/usage/item-presets.md explains item meta presets.
• docs/usage/collections.md explains file-based collections.
• docs/recipes/README.md lists practical customization recipes.
• docs/recipes/zoo-client-handoff.md — operator step-by-step for a zoo / wildlife park showcase (wizard + studio + deploy).
• docs/client-intake.md provides a reusable first-site client brief.
• docs/usage/client-scaffold.md explains how to create a separate client site scaffold.
• docs/usage/scaffold-templates.md explains supported scaffold templates and their boundaries.
• docs/usage/manual-client-setup.md explains manual client setup when no template fits.
• docs/product/positioning.md explains the product direction.
• docs/product/micro-cms-positioning.md explains the micro-CMS contract and WordPress comparison.
• docs/product/micro-cms-epic.md tracks the micro-CMS epic and issues.
• docs/product/product-levels.md explains developer-assisted, guided and no-code levels.
• docs/product/no-code-roadmap.md explains the staged no-code authoring roadmap.
• docs/usage/site-wizard.md explains the guided setup wizard.
• docs/usage/studio.md explains Studio and Atelier Desktop authoring.
• docs/architecture/adr-0001-configurable-showcase-kit.md explains the main architecture decision.
• docs/architecture/adr-0002-local-studio-research.md records local studio architecture research.
• docs/architecture/adr-0007-production-safe-studio-desktop.md records the production-safe authoring decision.

Support

Atelier-Kit is open-source under the MIT license.

People who can configure it themselves can use it freely.

People who want help configuring, customizing or deploying it may support the author or request paid setup/customization work.

To report bugs, suggest scoped features or improve docs, see CONTRIBUTING.md. Please use the GitHub issue templates — blank issues are disabled.

Status

Atelier-Kit is an early-stage micro-CMS for creative showcases — file-based content, local Studio / Atelier Desktop authoring, and static-friendly deploy.

See docs/product/micro-cms-positioning.md for scope and maturity.