Visual system

Every chart and diagram on this site is inline SVG generated from the same data as the tables beside it, styled from the same tokens as the surrounding page, and animated under one motion policy. This page is the catalogue: for each layout, the decision that selects it, a text blueprint, and the rendered component.

Principles¶

Four rules that decide what a figure is allowed to do. They are the reason no chart here carries a heat map, a gradient, or a rounded corner.

Colour classifies

A mark's colour repeats the classification axis it belongs to — static, dynamic, collected, manual, ownership. It never encodes magnitude, and it never ranks. A bar and a status tag describing the same value always agree.

Every number is written

A bar carries its value as text, a point carries its name, an axis carries its ticks. Removing all colour from the page loses a grouping, never a fact.

Figures are data, not decoration

A figure appears only where it says something the adjacent table cannot. There are no hero images and no illustrative graphics; a figure that repeats its caption is deleted.

Motion is state, not entrance

Animation shows a value arriving or a state changing. Nothing loops except where the loop is the subject, and every rule is inside a reduced-motion guard.

Motion system¶

Three durations and two easings. A transition that cannot be assigned one of them is not added.

linear — reserved for continuous motion that must not appear to decelerate: streaming pipeline dashes, the flywheel.

--ease, cubic-bezier(.2,.6,.2,1) — the default for state change: hover, focus, colour.

--ease-out, cubic-bezier(0,.7,.3,1) — arrivals: bars growing, lines drawing, a figure entering the viewport.

Specimen tracks replaying the three timing functions. With prefers-reduced-motion: reduce set, the pucks hold still and every rule below is inert.

Token	Value	Role	Applied to
`--dur-fast`	120 ms	Pointer feedback	Tag and cell hover, value labels appearing on a chart mark
`--dur-base`	220 ms	State change	Card hover lift, navigation colour, focus ring
`--dur-slow`	480 ms	Arrival	Bars growing from the axis, boxes fading in, the permalink flag
`--dur-draw`	1100 ms	Path drawing	Line series drawn along `stroke-dashoffset`
Stagger `.d1`–`.d8`	60 ms each	Sequencing	A series reads left to right instead of arriving at once
`animation-timeline: view()`	Scroll-linked	Trigger	Where supported, a figure animates as it enters; elsewhere it animates on load

The complete motion vocabulary. Durations are declared once as custom properties; no component defines its own timing.

Reduced motion is the floor, not a downgrade. Every animated rule on this site sits inside @media (prefers-reduced-motion: no-preference), so the reduced state is the plain stylesheet rather than a stripped variant of an animated one. Bars are drawn at full width, lines at full length, and no information is carried by the animation itself.

Quantitative charts¶

Seven layouts covering comparison, trend, distribution, composition, and schedule. Each is drawn from the atlas dataset rather than from sample numbers, so the figure on this page is the same figure that appears in context.

Bar chart

Use when: one categorical dimension is compared on one measure, and the category labels are too long to fit under columns.

Cat A: [========]      80
Cat B: [=====]         50
Cat C: [==========]   100
       0 ------------ max

Indexed entries per family. Bars grow from the axis on entry; hovering or tabbing to a row raises it and shows the full note. Source: this atlas's index.

Column chart

Use when: the categorical dimension is itself ordered — decades, versions, releases — so position along the axis carries meaning.

 9 |           #
 6 |        #  #
 3 |  #  #  #  #  #  #
 0 +--------------------
   50s 60s 70s 80s 90s 00s

First appearances per decade. The empty 2020s column is the finding, not a gap: the decade's activity is in language revisions rather than new general-purpose languages.

Line chart

Use when: a measure is continuous over an ordered axis and the shape of the change matters more than any single value.

Val ^            _.-*
    |        _.-*
    |    _.-*
    +------------------> Time

Cumulative index size against new entries per decade. The line draws itself along its own path length; each point exposes its value on hover or focus.

Quadrant / 2×2

Use when: two independent axes place items relative to each other, and the interesting content is which quadrant something falls in, not its exact coordinate.

        Checked early
   (Static + GC) | (Static + manual)
 GC ------------+------------ Manual
   (Dynamic+GC) | (Dynamic+manual)
        Checked late

Twelve languages on two classification axes. Positions are ordinal, not measured — the chart shows grouping, and deliberately carries no numeric scale to be over-read.

Radar / spider

Use when: three or more comparable subjects are scored on the same small set of axes and the shape of the profile is the point.

              [Safety]
                 |
     [Speed]---\ | /---[Interop]
               \|/
       [Tooling]-+-[Simplicity]

Editorial scores on five axes, stated as such. A radar is the one layout here whose values are a judgement; it is used for shape comparison only and never totalled into a score.

Gantt

Use when: several items occupy spans on one shared axis and the overlap between them is the question.

Task 1: [====]
Task 2:     [======]
Task 3:           [===]
        W1  W2  W3  W4  W5

Language mode lifetimes. Swift's modes are cumulative rather than successive — every mode a compiler has ever shipped stays selectable per module, which is what the overlapping bars show.

Stacked bar

Use when: each category splits into parts of a whole and both the total and the split matter.

Family A |####----|  8
Family B |######  |  6
         collected  manual

Memory model composition per family. The segment colours are the same ones the memory pages and the status tags use, so the chart needs no legend of its own to be read against them.

Pyramid / funnel

Use when: levels are ranked and each one rests on the one below, or a population narrows at each step.

        /  \
       / L1 \    (strategic)
      /------\
     /   L2   \  (tactical)
    /----------\
   /     L3     \ (foundational)

The strata a language sits on. Width encodes breadth of responsibility, not quantity; the layout is chosen when the resting-on relationship is the message.

Layers

Use when: the same stacking is better read as equal tiers, because each one has a name and a note rather than a size.

+-----------------------------+
| Layer 3: Presentation       |
+-----------------------------+
| Layer 2: Domain services    |
+-----------------------------+
| Layer 1: Infrastructure     |
+-----------------------------+

The swiftc lowering stack. Layers is the right layout when tiers are equal in importance and the reader needs the note beside each one; a pyramid would falsely imply the base is the largest.

Venn

Use when: two sets overlap and naming the intersection is the whole point.

     /-----\      /-----\
    /   A   \    /   B   \
   (    ( A and B )       )
    \       /    \       /
     \-----/      \-----/

Static typing and tracing collection are independent choices: ten indexed languages take both, which is why this atlas treats type discipline and memory model as separate axes rather than one spectrum.

Structural diagrams¶

Six layouts for things that have parts. The distinction that decides between them is whether the relationship is containment, descent, connection, or reference.

Architecture

Use when: components, tiers and the connections between them, where the reader needs to know what talks to what.

[Client] --> [API Gateway] --> [Service]
                  |              |
                  v              v
              [(Queue)]     [(Database)]

The Swift build pipeline as components. The dashed animated edge marks the one connection that leaves the compiler process: macro expansion runs in a separate sandboxed plugin.

Nested / box-in-box

Use when: the relationship is containment — every inner thing is inside exactly one outer thing.

+---------------- Module ------------+
| +---------- File ----------------+ |
| | [Type A]      [Type B]         | |
| +--------------------------------+ |
+------------------------------------+

Swift's access levels are defined by containment, which is why they are drawn this way: internal stops at the module boundary, package at the package boundary, and private at the enclosing declaration.

Tree

Use when: a single root descends into children and no node has two parents.

          [ Root ]
         /   |    \
      [B1]  [B2]  [B3]
      /  \    |
   [L1] [L2] [L3]

Swift's type kinds. A tree is correct here because the division is exhaustive and disjoint; where a thing can have several parents, the nested or architecture layouts are used instead.

Org chart

Use when: the tree encodes ownership and routing — who decides, who is asked, where a change goes.

          [ Core team ]
        /              \
   [ Workgroup ]    [ Workgroup ]
    /       \         /      \
 [SG]      [SG]    [SG]     [SG]

Swift project governance. An org chart differs from a tree only in what the edge means — here it is “delegates authority to”, which tells a contributor where a proposal is decided.

ER / data model

Use when: entities have identity, fields and keys, and the cardinality between them is load-bearing.

+-------------+      +--------------+
| PACKAGE     |1    *| TARGET       |
+-------------+------+--------------+
| PK name     |      | PK name      |
|    products |      | FK package   |
+-------------+      +--------------+

A package manifest as a data model. The cardinality labels are the content: the language mode is a property of the target, not the package, which is what makes incremental Swift 6 migration possible.

Timeline

Use when: events sit at points on one axis and the reader needs their order and their spacing.

--(2014)---[ 1.0 ]---------------->
--(2019)---[ ABI stable ]--------->
--(2024)---[ Swift 6 ]------------>

Six milestones on one axis. Cards alternate above and below the line so labels never collide; the axis is ordinal, and unequal real intervals are not implied to be equal.

Loop / flywheel

Use when: the process has no end state — its output is its own next input.

        --> [Build] --
       /              \
  [Monitor]        [Deploy]
       \              /
        <-- [Test] <--

The Swift Evolution cycle. The ring rotates continuously because the loop itself is the subject; this is the only figure on the site that animates indefinitely.

Flow and process¶

Five layouts for things that happen in an order. The choice between them is whether the axis is logic, time, actor, or data.

Flowchart

Use when: a decision branches the path and the reader has to follow one branch to an outcome.

   [Start] --> < Decision? >
                  | Yes  | No
                  v      v
            [Action A] [Action B]

The per-module migration decision. A flowchart earns its space only when there is a real branch; a straight run of steps is a process flow instead.

Process flow

Use when: the steps are sequential with no branch, and naming the handoffs is what the reader needs.

[Intake] -> [Validate] -> [Execute] -> [Log]

The four stages of swiftc, with the artefact that crosses each boundary named on the edge. Moving dashes indicate direction without an animated legend.

Data flow

Use when: the diagram is about what moves between stages, and the transport or schema is as important as the stage.

[Producer] ==(Kafka)==> [Spark] ==(S3)==> [DW]

Macro expansion as a data flow. The same layout as a process flow, with the payload rather than the step carrying the label — here it matters that the plugin receives and returns syntax, never types.

Sequence

Use when: several participants exchange messages and the ordering between them over time is the subject.

Actor     Service      DB
  |          |          |
  |--req---->|          |
  |          |--query-->|
  |          |<--rows---|
  |<--res----|          |

Actor reentrancy, which is hard to state in prose and obvious on a time axis: the suspension in the middle releases the actor, so any state read before the await may be stale after it.

State machine

Use when: a thing occupies exactly one of a fixed set of states and named events move it between them.

(Draft) --[Submit]--> (Review) --[Approve]--> (Live)
   ^                     |
   +-------[Reject]------+

A Swift task's lifecycle. The back edge is the point: cancellation sets a flag rather than stopping the task, so the transition out of Cancelled happens only when the task next checks.

Swimlane

Use when: the same process crosses several actors and the handoff between them is where the cost or the risk is.

Lanes  | Step 1    Step 2    Step 3
User   | [Req] ------+
Ops    |             v
       |          [Proc] ---> [Done]

Migration as a cross-functional process. The lane change is the content: the compiler, not the reviewer, is the participant that finds data races, which is what changes the review's job.

Futures¶

What this design system is not doing yet, and why. Recorded as decisions rather than a backlog, so a later reader can tell a deliberate omission from an oversight.

Platform capability	Availability	What it would buy	Decision here
`animation-timeline: view()`	Shipping in Chromium and Safari	Figures animate as they enter the viewport, with no scroll listener	In use behind `@supports`; elsewhere figures animate once on load
`@view-transition`	Shipping for same-document; cross-document rolling out	Cross-page navigation could keep the header and nav fixed while the article changes	Not adopted: the site is nine static pages and the transition would be decoration
Container queries	Interoperable	A chart could choose its own label density from its own width instead of the viewport's	Used for the motion specimens; charts still key off the viewport
`text-wrap: balance` / `pretty`	Interoperable	Headings and captions break without a one-word last line	Candidate; needs checking against the dense table captions first
Dark colour scheme	Available now	A second token block under `prefers-color-scheme`	Deliberately not shipped: the palette is tuned for contrast on paper-white and would need re-deriving, not inverting
`@scope`	Shipping in Chromium and Safari	Component styles could be bounded without class prefixes	Not needed at this size; the whole stylesheet is under 20 KB
Scroll-driven progress indicator	Available now	A reading-progress rule on long reference pages	Candidate for the Swift article, which is the only page long enough to want one

Availability describes browser support at the time of writing, August 2026. Every row marked as in use is behind an @supports query or a media query, so no page depends on it.

The constraint that holds

No runtime framework and no JavaScript. Every interaction on this site — scroll-triggered figures, hover values, keyboard-scrollable tables, focus rings — is CSS and SVG. Anything that cannot be built that way is not built.

What would change that

Sorting and filtering the comparison matrices are the only features worth script, and only if the tables outgrow reading. Until then, ordering is editorial and stated in each caption.

How a figure gets added

A generator in viz.py, called with real data from atlas.py. A figure whose numbers are typed in by hand rather than derived is a diagram, and is labelled as one.