swiss-atelier

6 files shipped with this skill. Inline text is the catalog copy. The upstream link is the source repository.

• skills/swiss-atelier/SKILL.md4.5 KBe9b32bca02bbupstream ↗

  ---
  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.
  

• skills/swiss-atelier/references/authoring.md3.5 KB86940a96be03upstream ↗

  # 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.
  

• skills/swiss-atelier/references/diagrams.md4.7 KBe6436164e83fupstream ↗

  # 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.
  

• skills/swiss-atelier/references/distribution.md3.6 KBa65abb814480upstream ↗

  # 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/[email protected]/dist/atelier.css">
  <script src="https://cdn.jsdelivr.net/gh/Jeonkwan/[email protected]/dist/atelier.js" defer></script>
  ```
  
  Matching tokens: https://cdn.jsdelivr.net/gh/Jeonkwan/[email protected]/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/[email protected]/dist/atelier.css">
  <script src="https://cdn.jsdelivr.net/gh/Jeonkwan/[email protected]/dist/atelier.js" defer></script>
  ```
  
  Matching tokens: https://cdn.jsdelivr.net/gh/Jeonkwan/[email protected]/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.
  

• skills/swiss-atelier/agents/openai.yaml266 Beac2288ea732upstream ↗

  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
  

• README.mdupstream ↗

  Contents are not inlined in the catalog. Open the upstream file.

Plain-text copy, no login: /skill-bundles/jeonkwan-swiss-atelier-design-system-skills-swiss-atelier.md