Illustrations and artwork

An illustration supports a tool or an article without an explanation. It gives a card a visual register after its heading and summary have named the subject. If a reader must understand a position, a connection, a quantity or a label in the picture, use a diagram.

That separation makes an illustration safe to crop or reduce. The copy still carries the subject when a decorative edge leaves the frame. A diagram cannot make the same trade, because its positions and labels are the claim.

An illustration sits in an explicit media slot. It is never a page ground behind text. Page surfaces stay flat, and the frame shows where decoration ends and content starts.

The language#

One person, object or still-life gesture, reduced to five to eight broad, hard-edged silhouettes.
A flat, almost orthographic view. Use overlap and at most two flat tones per object instead of perspective, materials or light.
Near-black charcoal, warm greys and muted taupes on a quiet, almost neutral warm-white ground.
One contained field of regular halftone dots and exactly one small #FF8700 detail. Neither carries a meaning.
No text, labels, arrows, charts, workflows, code or UI screens.

Every illustration is a 1200 × 750 WebP with crop-safe space around its subject. An image tool hands over a PNG, and the tree keeps the WebP at quality 0.86, with its transparency. make webp ARGS=<file.png> writes it beside the PNG. The same file serves light and dark mode. Its warm-white ground is the canvas of the image, not a match for the page. A second dark rendering is a duplicate asset whose composition drifts.

The set#

Illustrations — the set

Another one#

The rules above with the generator's vocabulary: the medium, the negative constraints, the choice of subject. It stands here in full because it is a thing to hand over. Copy the whole block and replace [SUBJECT], the one field that changes. A new medium or a new rendering language starts a second style, and a set in two styles is no set.

The prompt carries no list of subjects already drawn. packages/frontend/assets/placeholders/ owns that list. A copy in the prompt is an inventory that falls behind the assets.

The illustration prompt — replace only the subject

markdown

# Editorial spot-colour illustrations

An illustration gives a tool or an article a visual register without an
explanation. A diagram carries a claim. An illustration only supports the
subject the heading and summary beside it name. If a reader must understand
a position, a connection or a quantity in the image, draw a diagram instead.

## The fixed language

- **Format:** 1200 × 750 PNG. One file serves light and dark mode. There is
  no mode pair.
- **Composition:** one person, object or still-life gesture, drawn as five to
  eight large silhouettes in a flat, almost orthographic view. Leave
  generous, crop-safe space around it.
- **Colour:** a quiet, almost neutral warm-white ground, near-black charcoal,
  warm greys and taupes, plus exactly one small `#FF8700` detail. No second
  accent.
- **Form:** broad, hard-edged matte planes with simplified proportions. A
  sparse dark line can describe a cable, an edge or a joint, never a relation
  or a process.
- **Texture:** one regular halftone field in one contained plane. It is the
  print texture of the illustration, not the dashed state of a diagram.
- **Depth:** use overlap and at most two flat tones per object. You can add
  one pale, shape-like ground wash. Realistic cast shadows, highlights,
  materials and continuous modelling are out. The wash does not license a CSS
  shadow or an interface gradient. The linked card's lit frame stays the only
  one.
- **People:** adult proportions, quiet posture, no identifiable facial detail.
- **Accessibility:** the files are decorative support. Use an empty `alt`
  when the copy beside it already names the subject.

A hero uses a cut-out of the same language, with `plain`. It is a transparent
PNG with no ground and no wash. Its tones are warm off-white, warm grey and
taupe, with no near-black plane. So it reads on the page in both modes.

## Prompt

Replace `[SUBJECT]` and leave the rest unchanged:

```text
Use case: stylized-concept
Asset type: decorative card illustration, wide 8:5 landscape

Primary request: Create a mature editorial spot-colour illustration of
[SUBJECT] for a restrained technical design system.

Style/medium: flat drawn editorial illustration with a restrained
cut-paper/printmaking character; broad hard-edged matte silhouettes;
deliberately simplified geometry; at most two flat tones per object; one
controlled field of regular vintage halftone dots.

Composition/framing: 1200 × 750; one clear subject or still-life gesture;
flattened, almost orthographic view with very shallow perspective; generous
nearly neutral warm-white negative space matching #F7F6F2; crop-safe on all
sides; readable at card size; no border or frame.

Colour palette: warm off-white, near-black charcoal, warm grey, muted taupe,
and exactly one small vivid orange #FF8700 element. No other hue.

Rendering rules: five to eight dominant silhouettes; clean simplified
contours; no small functional detail. A sparse line may describe a cable,
edge or joint but must not form a process or diagram. Put the halftone inside
one contained object plane only. If grounding is needed, use one pale flat
wash shaped like a shadow, never realistic lighting.

Constraints: decorative, not explanatory; no text, letters, numbers, logos,
watermark, labels, arrows, charts, workflows, code or UI screens.

Avoid: photorealism, product rendering, realistic perspective, realistic
materials, lenses, reflections, highlights, continuous shading, cast-shadow
gradients, paper grain, cream or parchment backgrounds, bright multicolour
palettes, dramatic lighting, glossy 3D, childish character design, retro
travel posters, speech bubbles, dense detail, fine hatching and decorative
clutter.
```

## The subject

One concrete thing, taken from what the heading beside it names: an object,
or a person with an object. The copy carries the subject, and the image only
sets a register beside it. So the thing itself is enough, and the idea behind
it is not the subject.

Draw it at rest, not at work. A drawer with no cards in it, an unwritten
sheet, one module outside its socket. The moment before or after the work
reads as an object. The work itself needs position, sequence and quantity,
and that is a diagram.

Which subjects a set has spent is a property of that set, not of this prompt.
The prompt produces one image and knows nothing of the others. Somebody who
sees all the cards at once composes the view that shows them.

Artwork#

Every picture is a link. A drawing, a photograph, a mark in a bar: one <img> that points at one file. sds-image does that, sds-figure does it inside its frame, and the Guides theme does it for the signet and every picture in a document. Nothing about the file has to be true for the picture to arrive, and nothing reads the file first.

The cost is the mode. An <img> renders its file in a document of its own, where --text-primary does not exist. So a drawing keeps the fallback colour its author wrote on a page that has gone dark. So the surface under it does not follow the reader either; see its ground.

A reference, <use href="drawing.svg#part">, clones the shapes into the page, where inherited properties reach them. That file then arrives in the mode of its page. The fragment is the reason this is not the mechanism here.

Why not a reference#

A reference resolves against a fragment that names an id inside the file. That puts two demands on a system, and the second one ends it:

every drawing needs a named root, in every project that points at one;
something has to open the file to make sure of that before the renderer writes the page. A reference into a file without that id draws nothing: no error, no fallback, a hole.

SVG 2 removes the fragment. <use href="drawing.svg"> means the file's root, and both demands go with it. Chrome ships that since 137; Firefox and Safari do not. Until they do, a reference costs every consumer a file contract and pays a page that is blank outside Chrome. This page records the condition. When the other two ship it, a reference works on the artwork as it stands, and the mode comes back for free.

What a file has to do#

Two lines, and neither changes the drawing.

Colour the shapes	`fill="var(--text-primary, #18181B)"`, `stroke="var(--accent, #FF8700)"`: the token first, the hex behind it
Nothing else colours it	no rule in a `<style>` block, and no `fill` or `color` on the root. A drawing from a spec carries its faces in one, and only faces

A file written that way is ready for the day a page can reach into it, and it loses nothing until then. The hex is what an <img> renders. It is also what the file renders on its own: in a tab, from a README, in a favicon slot. The fallback belongs to the drawing, not to the text scale, so a contrast adjustment does not redraw a brand mark.

The drawings this system ships name a root as well, <g id="soul-ref">. That is the card generator's handle: make diagrams reads the shapes out from under it for the specimen cards. See Diagrams.

A comment must not contain a double dash. -- is not valid inside an XML comment, and a browser parses an SVG as XML. A file that is not valid draws nothing, as a reference, as an image and as a favicon, with no message. Every token in these files spells two of them, so a note that explains var(--token, #hex) breaks the drawing. Write "a var() with a hex fallback". make diagrams refuses a file with one.

Where the colour has to live#

These rules are about a reference, which is not how a page shows a picture today. They are the reason for the file contract, and what defeats it the day a page can reach in. A reference clones the shapes, and less travels with them than it looks.

A rule in the file wins over the token. A <style> block reaches the shapes it matches after a reference too, and a CSS rule beats a presentation attribute. So .ink { stroke: #8A8378 } defeats stroke="var(--text-primary, #18181B)" on the same shape, and the mark is grey on every page.

A colour on the root wins too. color or fill on the <svg> lands on the clone and inherits down over what the page carries. So the shapes cannot say currentColor with a fallback on the root: the fallback is then the answer everywhere.

What the file inherits does not travel. A custom property on the file's own root does not reach the clone, which inherits from the page. So a file cannot bring its own mode switch, and does not need one. The hex covers the page that declares nothing, which today is every page.

The tokens to use#

`--text-primary`	the ink: the mark, the outline, the drawing itself
`--text-secondary`, `--text-muted`	a quieter part: a label, a secondary line
`--accent`	the one thing the drawing is about. One per drawing
`--surface-canvas`, `--surface-sunken`	a ground the drawing brings with it
`--border-subtle`, `--border-strong`	a hairline the drawing draws itself

Diagrams has the rest of what a diagram can use, and its numbers.

A signet of your own#

The mark in a documentation bar is a configuration, not a shipped file. It is a file in the documentation tree, and this system has no opinion about what it depicts.

There is no signet component. A drawing inside an element copies the optical files into TypeScript and binds a consumer to this system's own mark. sds-image supplies the artwork mechanism. .sds-signet supplies only the layout a mark needs and leaves its size to the caller.

guides.xml

xml

<extension class="TYPO3\Soul\GuidesTheme\DependencyInjection\SoulExtension">
    <signet>_images/signet.svg</signet>
    <brand>Acme</brand>
    <product>Your product</product>
</extension>

The bar shows the mark like every other picture, as a link. So an SVG and a PNG both work, and both are the same picture in both modes. Write the SVG's colours as the file contract asks anyway. That makes the mark right the day a page can reach into it, and the hex is what draws it until then.

Name the drawing made for 24. The bar draws its mark at 24, and a signet is crisp only in the box of its drawing. The 16 file scales by 1.5, which puts every straight edge on a half pixel. The other optical sizes belong in the tab, one <favicon> per slot; see Configuration.

Draw the mark itself to the construction. Brand has the rules, and docs/design-system/brand-and-imagery/signet-prompt.md is that construction as an instruction for a drawing tool.

The ground it stands on#

A drawing arrives in the colours of its export, the one thing on the page that does not follow the reader into dark. So its ground does not either. A figure's frame, a card's picture and the viewer all take --surface-art, the one surface with a single value for both modes. Dark line art on a dark ground is the page against its own picture. A photograph brings its own ground, and the page leaves it alone.

A screenshot#

A picture of a surface as it stands, in a document that discusses it: a concept paper's "where it stands", a review of a page. It is a link like every other picture, an <img> in sds-figure with the claim under it and zoomable for the detail. A raster arrives in the mode of its capture, so the frame under it takes --surface-art, as under a drawing.

The ones this system ships are of its own screens. make look takes them at 1440, cropped to a window, and they live in packages/frontend/assets/screenshots/. They are a story's fixture, like the illustrations. The design agent gets them beside the screen that shows them, and the drop-in does not carry them.

When it draws nothing#

A picture that does not appear has one cause left, and it is in the file. A comment carries a double dash, so the file is not well-formed. A browser parses an SVG as XML. A file that is not valid draws nothing, as an image and as a favicon, with no message.

Specimen cards are the one place artwork is not a link. They open from disk with no server, so the card generator puts the drawing's shapes into the card itself: scripts/diagrams.ts and packages/frontend/src/components/art.static.ts. That is why a specimen shows the drawing in both modes and a page shows one picture in both.