# swiss-atelier

Adopt this skill: https://proskills.md/skills/other/jeonkwan-swiss-atelier-design-system-skills-swiss-atelier

Page: https://proskills.md/skills/other/jeonkwan-swiss-atelier-design-system-skills-swiss-atelier
This document is the public skill bundle for that page. It contains SKILL.md and every helper file the catalog carries. No login is required.

## File: skills/swiss-atelier/SKILL.md
size: 4648
sha: e9b32bca02bb5cf50fbdcfe69b414143546bfed0
upstream: https://github.com/jeonkwan/swiss-atelier-design-system/blob/main/skills/swiss-atelier/SKILL.md

```text
---
name: swiss-atelier
description: Create or edit technical explainers, ADRs, and editorial diagrams with Swiss Atelier only when the user explicitly invokes $swiss-atelier or asks to use Swiss Atelier. Generic writing, diagram, or visual-style requests do not activate this skill.
---
# Swiss Atelier

Apply this skill only after an explicit user invocation, such as `$swiss-atelier` or “use Swiss Atelier.” Installation, discovery, a reference mention, or matching visual preferences does not activate it. Preserve the requested output format; if unspecified, retain the current conversation/document format. Create HTML only when the user requests HTML or a web page. Swiss supplies visual identity and an authoring method, not domain facts or permission to change formats.

## Establish the explanation

Reuse known audience, reader task, conclusion/decision, sources, unknowns, and delivery constraints. Ask only unresolved questions that would change the result. For drafting and reader checks, read [authoring](references/authoring.md). For any diagram, first choose its representation and define its semantics using [diagrams](references/diagrams.md). Missing evidence stays unknown.

## Load one coherent asset set

In this checkout, copy `templates/starter-adr.html` or `templates/starter-diagram.html`; both use the adjacent `dist/` bundle. Copy this entire skill directory, including `references/`, when installing it elsewhere.

For hosted use, see [distribution](references/distribution.md): choose current-main assets/guidance together, a complete immutable release, or a vendored checkout. Do not combine pinned CSS with later tokens or templates. Consumers need `atelier.css` and optionally `atelier.js`, never Tailwind or the specimen's `site.css`/`site.js`.

## Preserve the identity; adapt the layout

- **Identity:** Gallery Stone paper, white cards, Subtle Zinc wells, 1px hairlines, 4px radii, no shadows/blur. Fraunces display, Literata prose, Geist UI/tables, Geist Mono technical text. Use explicit `atelier-h1`/`h2`/`h3` classes.
- **Defaults:** Fraunces 500, tracking −0.02em; Literata 440, 0.98rem, line-height 1.68, tracking −0.005em, measure 60–68ch. Adapt size, measure, wrapping, and density for the reader and delivery surface; these are brand calibration, not universal readability evidence.
- **Signals:** Orange `--accent-primary` for one or two focal elements; teal `--accent-secondary` for recommendations or supported verification. State proposed/accepted/verified/unknown in words; acceptance is not empirical verification. Use `--ink-focal` / `--ink-positive` for small colored text on paper/tints. Check actual pairings.
- **Components:** `atelier-card`, `atelier-well`, `atelier-callout-focal`, `atelier-callout-verified`, `atelier-callout-note`, `atelier-badge-orange`/`teal`/`neutral`, `atelier-code-inline`/`focal`, `atelier-table`. Add document-local layout CSS. Tokens specify shared roles, not complete specimen re-theming.
- **Diagrams:** Structural 4px grid, orthogonal off-axis connectors with 8px elbows, connectors before nodes, opaque label masks. Font sizes need not follow the grid. Preserve readable labels at the rendered scale and local scrolling for essential two-dimensional views; provide a complete nearby text equivalent.

## Code and delivery

Use `<pre data-atelier-code data-lang="rust">`; escape source HTML (`&lt;`, `&amp;`). Common token sets: Rust, TOML, SQL, JS/TS, Python, shell. One-based `data-focal-lines="3,5"` and `data-verified-lines="7"` add styling, never evidence. `SwissAtelier.initAll()` processes new blocks; the highlighter is line-oriented, not a parser. For complex constructs use a dedicated tokenizer with `.syn-*` classes. Await `SwissAtelier.copyToClipboard(text)` and handle rejection.

Optional companions: doc-coauthoring can help with audience/structure/review; diagram-design with representation/semantics/layout. Keep Swiss fonts, colors, surfaces, and geometry; the user's format and constraints govern delivery. No companion installation, global edits, or external scripts are required. The linked methods work on their own.

Check the reader's conclusion, rationale, uncertainty, and next action; then inspect desktop/narrow layout, zoom/spacing, fallback fonts, keyboard focus, diagram equivalents, tables, and copy success/failure. Use the matching accessibility guide from your chosen checkout/release. This is a web-first system; print, no-JS, offline typography, and CJK extensions are outside the verified delivery scope.

For system changes, read repository `AGENTS.md` and `CONTRIBUTING.md`; build and test generated assets.
```

## File: skills/swiss-atelier/references/authoring.md
size: 3610
sha: 86940a96be0341e346f1e554db61398bf31c5378
upstream: https://github.com/jeonkwan/swiss-atelier-design-system/blob/main/skills/swiss-atelier/references/authoring.md

```text
# From facts to an explanation

Use this method for an explainer or decision record. Reuse supplied answers; a filled brief is useful working context, not a compulsory interview or a required section in every output.

## Brief and evidence

Establish who is reading and what they already know; the question they must answer or action/decision they must take; the document kind and main conclusion; source facts with provenance; assumptions, conflicting accounts, and unknowns; and output constraints such as format, viewport, available assets/tools, and deadline. Infer routine layout choices. Ask only when an unresolved issue changes content or acceptance; otherwise state the assumption and proceed.

Separate observed, estimated, synthetic, and proposed claims. A recommendation or accepted decision does not prove its effect. Attach source/status to claims near where they may be copied. For a measurement record its value, units, definition/denominator, observation period, baseline/comparator, source, and uncertainty where relevant. If unavailable, say unknown; do not fill a metric component with invented data. Synthetic examples must say synthetic at the point of use. A quantitative mark needs a defined scale and mapping; remove decorative progress bars that look measured. A qualitative map must not imply measured distances or a numerical ordering of categorical guarantees.

## Outline and draft

- **Explanation:** answer/takeaway → context and terms needed by this audience → causal reasoning or worked example → limitations and next action. Adjust for the task; do not force a decision record onto an explanation.
- **ADR:** title + lifecycle status → decision in brief → context/forces → decision and reasons → consequences (benefits, costs, risks). Add alternatives, evidence, owner/date, and supersession links when useful. Keep unknown evidence visible. Draft/proposed, accepted, rejected, and superseded describe decision lifecycle; verified describes a specific supported claim, never the whole document by default. Copy the repository's `templates/starter-adr.html` or the matching hosted template from [distribution](distribution.md).
- Choose prose, table, or a scoped diagram for each question using [diagrams](diagrams.md). Introduce unfamiliar terms and put the explanation next to the relevant figure. Disclose supporting detail without hiding the main conclusion.

## Reader check and refinement

Give a reader only the draft and necessary task context. Ask them to state the conclusion/decision, why it follows, a material consequence or alternative, what remains uncertain, and what to do next. For diagrams ask them to explain scope, each relationship/direction/condition, a deliberate omission, and the takeaway. Try the text equivalent without the image. Correct the output where an answer cannot be traced to it; correct admissions of missing information count as success.

For a repeatable evaluation save the input, allowed references, expected answers separately from the reader prompt, actual answers, ambiguities, and resolutions. Label agent inspection as agent inspection. Use representative humans before claiming human comprehension; an agent check is not a usability study or accessibility audit.

This local method adapts [Google's audience guidance](https://developers.google.com/tech-writing/one/audience), [Diátaxis](https://www.diataxis.fr/start-here/), and [Nygard's ADR proposal](https://www.cognitect.com/blog/2011/11/15/documenting-architecture-decisions). These are practitioner frameworks, not proof of one ideal outline or font size.
```

## File: skills/swiss-atelier/references/diagrams.md
size: 4803
sha: e6436164e83f032c8dcb869ebefb693df20125f9
upstream: https://github.com/jeonkwan/swiss-atelier-design-system/blob/main/skills/swiss-atelier/references/diagrams.md

```text
# Choose and explain a representation

Write the reader's question and takeaway before drawing. A picture is useful only if its organization helps answer that question.

| Reader question | Use | Semantic contract |
| --- | --- | --- |
| What is the single conclusion? | Prose | State the claim, reason, and uncertainty directly. |
| Which option has exactly which properties? | Table | Named rows/columns, units, definitions, sources, missing values. |
| What exists and how is it connected? | Architecture/topology | Name scope and abstraction; boxes are entities at that level; directed labeled edges assert a specific dependency or flow. Boundaries mean named ownership, trust, deployment, or scope only when stated. |
| Who sends what, in what order? | Sequence | Actors/lifelines, top-to-bottom ordering; arrows name messages and their direction; declare request/return styles. Vertical distance is not elapsed time unless scaled. |
| What can change and under which event/guard? | State | One entity's legal states; directed transitions labeled `event [guard] / action` as applicable; define initial/terminal states if known. No arrow means no asserted transition in the declared scope. |
| How do numerical values compare or change? | Chart, if data exists | Identify the numerical task, units, domain, scale, baseline, period, source, and uncertainty. Status colors are not automatically an appropriate data palette. |

## Before layout

Declare actual versus proposed/illustrative, audience, system/entity, scope, abstraction, source facts, and unknowns. List entities and meaningful relationships before styling. Label the intent of every arrow; name boundary, direction, color, line style, and size semantics in a key when they carry meaning. Decorative frames are not implicitly security boundaries. Do not invent services, retry policies, timings, or arrows to complete a shape.

For a **retry/timeout sequence**, establish initiator, receiver, request/response, timeout event, retry eligibility, attempt limit, and final failure behavior. If any is unknown, name it; use a note or a separate unresolved branch instead of inventing a duration or an extra service. Distinguish a return from another request, show conditional/repeated paths explicitly, and say which failures are omitted. Sequence communicates interaction order; use a state view when the question is which transitions are legal.

For a **lifecycle**, name the entity and event/guard for each transition. Define the time variable (age, remaining TTL, or replication lag) before writing thresholds. Preserve exact inequality boundaries across prose, configuration, code, and tables. If the source specifies only selected transitions, mark that scope rather than presenting an incomplete view as a full state model.

For a **system overview**, keep one abstraction per view, identify ownership/trust boundaries only if known, and separate message order into a linked sequence. Counts, legend, caption, and relationship summary must agree.

## Layout and equivalent explanation

Use Swiss typography and hairline surfaces. The 4px grid controls structural coordinates, not font sizes or a rigid node/label count. Route off-axis connectors orthogonally with 8px elbows; draw connectors before nodes and use opaque masks behind labels. Fit boxes to labels, wrap long text, and prefer overview + detail when a single canvas becomes dense. Report every material simplification and where the omitted detail or unknown is recorded.

Choose label size from the destination. The shipped examples use at least 14 CSS pixels at their minimum canvas width; this is a local starting point, not a WCAG minimum. Do not shrink a 960-unit canvas into a phone width. Use a named, keyboard-focusable local scrolling region, visible scroll guidance, and inspect loaded/fallback fonts, narrow screens, zoom, and user spacing. Split a diagram if scrolling obscures its reading path.

Give SVG a useful `<title>` and `<desc>` with resolvable IDs. Add nearby structured text containing the same entities, directed relationships, guards, scope, omissions, and takeaway. Associate it using `aria-describedby` when appropriate. A generic name or repeated title is not a complex-image equivalent.

Read the figure without oral narration, then read its text equivalent without the figure. Can both answer the same task? See the portable `templates/starter-diagram.html` in a checkout or its matching hosted copy via [distribution](distribution.md).

This method borrows clarity checks from the [C4 checklist](https://c4model.com/diagrams/checklist), without requiring C4 for every diagram, and text alternatives from [W3C complex-image guidance](https://www.w3.org/WAI/tutorials/images/complex/). Swiss geometry and typography remain local brand choices.
```

## File: skills/swiss-atelier/references/distribution.md
size: 3677
sha: a65abb814480e903cd277c54adc421f472b1efeb
upstream: https://github.com/jeonkwan/swiss-atelier-design-system/blob/main/skills/swiss-atelier/references/distribution.md

````text
# Keep guidance and assets together

Choose one source for the whole recipe. Local relative references in the skill folder resolve after copying that entire folder; repository templates and tokens must be copied/vendored separately or fetched from the same chosen source. This checkout contains 1.1.0; its additions are not in v1.0.0.

## Current-main consumption

The [site](https://jeonkwan.github.io/swiss-atelier-design-system/) and all Pages paths track the deployed `main` build. Fetch its [skill](https://jeonkwan.github.io/swiss-atelier-design-system/skills/swiss-atelier/SKILL.md), [tokens](https://jeonkwan.github.io/swiss-atelier-design-system/dist/tokens.json), [ADR template](https://jeonkwan.github.io/swiss-atelier-design-system/templates/starter-adr.html), and [diagram template](https://jeonkwan.github.io/swiss-atelier-design-system/templates/starter-diagram.html) from that same build. It is a moving target.

```html
<link rel="stylesheet" href="https://jeonkwan.github.io/swiss-atelier-design-system/dist/atelier.css">
<script src="https://jeonkwan.github.io/swiss-atelier-design-system/dist/atelier.js" defer></script>
```

## Immutable release consumption

Use the [entire v1.1.0 tree](https://github.com/Jeonkwan/swiss-atelier-design-system/tree/v1.1.0), including its complete skill folder (`agents/openai.yaml` and `references/`), templates, accessibility guide, and tokens. The skill requires explicit user invocation and preserves the requested output format.

```html
<link rel="stylesheet" href="https://cdn.jsdelivr.net/gh/Jeonkwan/swiss-atelier-design-system@v1.1.0/dist/atelier.css">
<script src="https://cdn.jsdelivr.net/gh/Jeonkwan/swiss-atelier-design-system@v1.1.0/dist/atelier.js" defer></script>
```

Matching tokens: https://cdn.jsdelivr.net/gh/Jeonkwan/swiss-atelier-design-system@v1.1.0/dist/tokens.json .

## Historical v1.0.0 consumption

For v1.0.0 use the [entire v1.0.0 tree](https://github.com/Jeonkwan/swiss-atelier-design-system/tree/v1.0.0), including that release's skill, template, accessibility guide, and tokens. It does not contain the newer authoring references, diagram starter, explicit-only invocation policy, or contextual text tokens. Do not apply 1.1.0 recipes to that old CSS.

```html
<link rel="stylesheet" href="https://cdn.jsdelivr.net/gh/Jeonkwan/swiss-atelier-design-system@v1.0.0/dist/atelier.css">
<script src="https://cdn.jsdelivr.net/gh/Jeonkwan/swiss-atelier-design-system@v1.0.0/dist/atelier.js" defer></script>
```

Matching tokens: https://cdn.jsdelivr.net/gh/Jeonkwan/swiss-atelier-design-system@v1.0.0/dist/tokens.json . For a future release, replace the ref consistently throughout the complete recipe only after that tag exists.

## Vendor a checkout

Copy `dist/atelier.css`, optional `dist/atelier.js`, `dist/tokens.json`, the chosen template, and matching guidance from one commit; record the commit. Template imports are relative to `../dist/`; adjust both when moving a page. Do not import raw GitHub CSS URLs. For single-file HTML inline the shared CSS and necessary runtime; the Google Fonts import still requires connectivity. The system has fallback fonts but does not promise identical offline typography.

The JSON generates shared CSS custom properties; `styles/atelier.css` consumes many of them. Changing `ink-focal`, for example, updates shared orange badge/code text and the specimen's contextual text roles, not orange brand strokes/fills. Some specimen colors, syntax demonstrations, layout coordinates, and treatment values are literal. This is a fixed-brand system with reusable roles, not a complete arbitrary-theme engine. Inspect affected contexts after changing a token.
````

## File: skills/swiss-atelier/agents/openai.yaml
size: 266
sha: eac2288ea732d01b261210f6d5960efe757e3712
upstream: https://github.com/jeonkwan/swiss-atelier-design-system/blob/main/skills/swiss-atelier/agents/openai.yaml

```text
interface:
  display_name: "Swiss Atelier"
  short_description: "Editorial technical documents and system diagrams"
  default_prompt: "Use $swiss-atelier to create a clear technical document in my requested output format."
policy:
  allow_implicit_invocation: false
```

## File: README.md
upstream: https://github.com/jeonkwan/swiss-atelier-design-system/blob/main/README.md

````text
# Swiss Atelier

A living information design system for technical explainers, architecture decision records, and editorial SVG diagrams. Swiss grid discipline meets Fraunces headings, Literata prose, and Geist UI and code.

**[Explore the living system](https://jeonkwan.github.io/swiss-atelier-design-system/)** · **[ADR starter](templates/starter-adr.html)** · **[Diagram starter](templates/starter-diagram.html)** · **[Agent skill](skills/swiss-atelier/SKILL.md)** · **[Contribute](CONTRIBUTING.md)**

This checkout is **1.1.0**. Use matching assets, templates, tokens, and guidance from one checkout or release. For stable consumption, use the complete `v1.1.0` release; Pages tracks deployed main.

## Start with the reader's task

- Write a decision: copy the [draft ADR](templates/starter-adr.html), then fill context, decision/reasons, consequences, evidence/unknowns, and next action.
- Explain relationships: use the [portable diagram](templates/starter-diagram.html) and [representation selector](skills/swiss-atelier/references/diagrams.md) before drawing.
- Integrate assets: use the two imports below or the [integration example](templates/starter-integration.html).
- Instruct an agent: load the [complete portable skill](skills/swiss-atelier/SKILL.md), including its references; optional companion skills retain Swiss identity.
- Inspect presentation: explore the nine-module specimen. Its storage-engine story and metrics are synthetic, not production evidence.
- Maintain the system: read [AGENTS.md](AGENTS.md) and [CONTRIBUTING.md](CONTRIBUTING.md).

Reuse supplied audience, outcome, source facts, assumptions/unknowns, and delivery constraints. Ask only unresolved questions that change the result. Draft an answer-first explanation or a decision-first ADR as appropriate. Ask a reader to recover the conclusion, reasoning, consequences, uncertainty, and next action. The [authoring method](skills/swiss-atelier/references/authoring.md) covers evidence, numbers, and reader checks.

## Use it in a page

Import the shared stylesheet and optional syntax-highlighting runtime. No framework or Tailwind dependency is required by consuming pages.

```html
<link rel="stylesheet" href="https://jeonkwan.github.io/swiss-atelier-design-system/dist/atelier.css">
<script src="https://jeonkwan.github.io/swiss-atelier-design-system/dist/atelier.js" defer></script>

<article class="atelier-card" style="padding: 2rem;">
  <h1 class="atelier-h1">A clear technical decision</h1>
  <p class="atelier-prose">Describe the context, tradeoffs, and outcome.</p>
  <pre data-atelier-code data-lang="js" data-focal-lines="1">const decision = "adopt";</pre>
</article>
```

Start with [templates/starter-adr.html](templates/starter-adr.html), which supplies decision structure; the separate integration example demonstrates code highlighting. When copying it into another project, update its two relative imports to the absolute URLs above or vendor `dist/atelier.css` and `dist/atelier.js` alongside your page. Use `atelier-h1` / `atelier-h2` / `atelier-h3` for headings; the bundle deliberately does not restyle every heading automatically.

The Pages URLs follow deployed main; use all guidance, tokens, templates, CSS, and JS from the same build. Use the adjacent relative bundle, vendor this complete checkout, or use the [complete v1.1.0 tree](https://github.com/Jeonkwan/swiss-atelier-design-system/tree/v1.1.0). The historical [v1.0.0 tree](https://github.com/Jeonkwan/swiss-atelier-design-system/tree/v1.0.0) remains available with its own matching guidance; it does not contain the new additions. See [distribution](skills/swiss-atelier/references/distribution.md) for complete pinned recipes and token coverage limits.

Fonts load from Google Fonts through CSS. System fallbacks remain available if the network is blocked. For a fully offline page, vendor appropriately licensed font files and replace the Google Fonts import. The line-oriented highlighter supports common Rust, TOML, SQL, JavaScript/TypeScript, Python, and shell tokens; it is a display helper, not a language parser. Dynamic code blocks can be formatted by calling `SwissAtelier.initAll()` again.

## Use it with an agent

The skill requires explicit user invocation: `$swiss-atelier` or “use Swiss Atelier.” Installing it, discovering its links, or requesting similar typography does not activate it. The skill preserves your requested output format; HTML requires an explicit HTML or web-page request.

For an HTML page, give an agent the [hosted skill](https://jeonkwan.github.io/swiss-atelier-design-system/skills/swiss-atelier/SKILL.md), [token file](https://jeonkwan.github.io/swiss-atelier-design-system/dist/tokens.json), and [starter](https://jeonkwan.github.io/swiss-atelier-design-system/templates/starter-adr.html), or use this prompt:

> Use Swiss Atelier to create an HTML page. Read https://jeonkwan.github.io/swiss-atelier-design-system/llms.txt and follow its linked skill. Import the shared CSS and runtime, preserve the typography and semantic colors, and verify keyboard access and mobile layout.

The Swiss skill works alone. Optional doc-coauthoring helps with structure/review; diagram-design helps with semantics/layout. Swiss supplies the visual identity, and the user supplies the subject, format, and constraints. No global skill changes or companion scripts are required.

For an agent that supports local skills, copy `skills/swiss-atelier/` into its skill directory. For example, from this checkout into another project's `.agents/skills/`:

```sh
mkdir -p /path/to/project/.agents/skills
cp -R skills/swiss-atelier /path/to/project/.agents/skills/
```

Use the directory supported by your agent. Copy `agents/openai.yaml` with the rest of the skill: its `policy.allow_implicit_invocation: false` disables automatic selection in supporting agents. Other agents must follow the same explicit-invocation rule in `SKILL.md`. A hosted `SKILL.md` or `llms.txt` helps discovery; it does not automatically install or activate a skill. Repository contributors should read [AGENTS.md](AGENTS.md).

## Run and maintain locally

Requires Node.js 22+ and Python 3 for the preview server.

```sh
npm ci
npm run build
npm test
npm run preview
```

Open [localhost:4173](http://localhost:4173). Built output lives in `_site/`. Pull requests run build and validation; pushes to `main` also publish GitHub Pages. Pages must use **Settings → Pages → Source → GitHub Actions**. See [the publishing guide](docs/publishing.md). Review the [implementation and validation report](docs/implementation-review-2026-10-26.md) for this release.

| Location | Purpose |
| --- | --- |
| `index.html` | Nine-module living specimen and interactive documentation |
| `dist/tokens.json` | Editable DTCG 2025.10 typed design tokens and CSS-name extensions |
| `styles/atelier.css` | Editable shared component styles |
| `styles/site.css`, `scripts/site.js` | Specimen-only styles and interactions |
| `dist/atelier.css`, `dist/atelier.js` | Public stylesheet and browser runtime; CSS is generated, JS is maintained directly |
| `dist/site.css`, `dist/site.js` | Generated specimen assets; not required by consumers |
| `templates/` | Working examples using only the public bundle |
| `skills/swiss-atelier/` | Portable agent skill and UI metadata |
| `scripts/`, `tests/` | Build, public-file packaging, link checks, runtime regressions |
| `docs/`, `CONTRIBUTING.md` | Human guidance, release process, and initial review |
| `deploy/` | Optional legacy GCS deployment; not used for Pages |

## Identity and adaptable defaults

Gallery Stone paper `#F4F4F6`, white cards, `1px` hairline borders, `4px` radii, no shadows. Fraunces 500 headings, Literata 440 prose, Geist UI, Geist Mono code. Reserve orange `#D9381E` for one or two focal elements; use teal `#0F766E` for recommendations or supported verification. Use contextual `--ink-focal` / `--ink-positive` for small text on paper and tints. Accepted decisions and veri
````