# Pavilion art direction

## What the style is

Pavilion uses **Mediterranean engraved pixel art**. The architecture combines Roman round arches and masonry, Romanesque vaults, and medieval Italian coastal towns. Loggias, tiled roofs, balustrades, cypresses and working harbours keep the places related. Fine square marks describe stone and water. Lines follow the material: short broken strokes on rock, repeated joints in masonry, horizontal marks on the bay. Dither supplies the tones between Paper, Mineral and Ink.

Use that name when briefing an artist. “Roman” describes the arch and structural proportions. “Medieval Italian” describes the buildings and townscape. “Engraved pixel art” describes how the picture is drawn. This is an invented coastal world; the references guide its architecture without making it a reconstruction of one historical period.

Keep the round arches, substantial stone piers and shallow tiled roofs consistent. Detail comes from joints, hatch marks and plants. A new scene should share the bay's scale and materials. Gothic spires, imperial monuments, fantasy castles and modern marinas belong to a different setting.

The pictures have the detail of an etching and the fixed grid of a raster. A roof edge should hold together when the image is opened at full size. From a feed, the same roof should read as one clear shape. The sky gives the picture room for a headline.

The current Bridge and Wallet sites are the visual reference. Keep the fine line work, restrained blue greys and low coastal views. Type and the doorway mark stay crisp. They are never pixelated to match the art.

## Why it suits Pavilion

The pavilion is a shared home. Its open sides and roof give Wallet a place in the same bay as Bridge. The doorway is the invitation into that home. The stone bridge supplies a visible crossing between two shores.

These are places people can recognise from one post to the next. A status note can use the lighthouse. A welcome post can use the doorway. Neither needs a new visual metaphor each week. The quiet sky also leaves enough room to say what a product does for Pearl.

The illustrations do not establish a security claim. An iron door cannot prove that a product is safe, and bridge arches cannot explain a proof system. Use accurate copy and crisp diagrams for those jobs.

## The world

The setting is a calm Mediterranean bay. Stone buildings, tiled roofs, cypresses, small boats and pearl farm float lines belong here. The same places return in daylight and moonlight.

| Place | Keep recognisable | Meaning and use |
| --- | --- | --- |
| Bay and bridge | Ten arches, plain level rail, village on the left, layered islands and mountains, lighthouse on the right headland, float lines in front | Pavilion Bridge. Crossings, how it works, proof posts and product updates |
| Pavilion | Shallow tiled roof and finial, four columns, stone terrace and balustrade, cypresses, two seated figures, bridge behind, lighthouse on the right | Pavilion Wallet and the shared Pavilion home. Wallet features, community and events |
| Coast | Domed church and bell tower above the right cliff, village, cypresses, a small arched bridge, sailboat on the left | Shared setting. Longer updates, community posts and general brand pieces |
| Doorway | Arched open door, two porch arches, tiled roof, right tree, cypresses, stone path and steps above the bay | Welcome, getting started and self custody. Keep the invitation visible |
| Harbour loggia | Three open round arches, shallow tiled roof, quay steps and one moored skiff | Community, introductions and shared Pavilion posts |
| Hill aqueduct | Two levels of round arches, cypress valley, low hill town and sea | Infrastructure and network explanations |
| Terraced gardens | Stone balustrades, central steps, fountain and cypresses | Ecosystem updates and general brand pieces |
| Tide courtyard | Cistern well, two arcade bays, worn paving and open sea | Wallet and account guidance |
| Vaulted archive | Three barrel-vaulted bays, closed books and a stone reading table | Documentation, proof explanations and release notes |
| Coastal watchtower | Squat stone tower, winding footpath, small bridge and pearl-farm floats | Status and watchtower explanations, without implying a guarantee |

Count the arches in the actual source before editing. The bay bridge has ten. The coast has a separate smaller bridge. Preserve that smaller bridge's own count; do not turn every bridge into the ten arch bay bridge. Camera framing can change between formats, but the place must remain recognisable. Never mirror the scene to solve a layout problem.

### The vignette library

Each subject has a day version on flat Paper and a night version on flat Ink. The edge of its ground or water dissolves into the surface through sparse dither. There is no rectangular scene boundary. The 1200×1200 files include a flat margin of at least 64 pixels on every edge.

| Subject | Topics | How to use it |
| --- | --- | --- |
| Pearl in an open oyster | Wallet, welcome | A small introduction to Pavilion's Pearl setting. This physical pearl does not replace the Pearl Research Labs token mark |
| One bridge arch | Bridge, proofs | A compact crossing motif. Keep its plain horizontal rail and two intact piers |
| Pavilion | Wallet, community, events | A shared place to gather. Use the isolated building when a full landscape is too busy |
| Lighthouse | Status, updates | A clear signal in the bay. Pair it with a specific status in type; do not add beams or warning glow |
| Doorway | Welcome, self custody | Getting started, entering the product and account guidance |
| Iron bound strongroom door | Vault, keys, self custody | Vault explanations and custody guidance. The small keyhole is a motif, never a security badge |
| Five buoys on a float line | Proofs, status, updates | Repeated checks and progress. Any actual five step process belongs in a labelled vector diagram |
| Sailboat | Bridge, community, events | A crossing or a shared activity. Avoid turning it into a claim about transfer speed |

Do not use a literal recovery phrase or private key in a picture. The door and its keyhole cover the custody topic without exposing secrets or inventing sample credentials.

## Day and night

Day has a Paper sky, pale cloud edges, Mineral water and Ink in the deep cuts of stone and foliage. Water stays mostly in the middle of the ramp. The lightest marks pick out the sunlit masonry and ripples.

Night has an Ink sky, a few small stars and one moon. Keep the same buildings and coast. Stone has dark planes and thin pale edges. A few windows can be lit. Water is dark, with broken horizontal marks where it catches moonlight. The bright reflection is narrow enough to leave dark water around it.

The moon belongs on the right, away from the left 60% used for headlines. Its diameter is usually about 4 to 6% of the source width. It has a hard pixel edge and a little surface detail. The original four places put the moon inside the quiet zone. The six additional places retain their original moon beside the scenery when the sky extends for portrait and square posts. A vignette has no moon, stars or sky.

Create night by editing the accepted day raw with new lighting. Do not use the quantiser's --invert flag for a night final. Inversion makes the wrong surfaces bright and supplies neither moonlight nor lit windows. The inverted example in the reject gallery shows this failure.

Avoid heavy cloud masses. Sparse stars should stay small when the image is opened at full size. Keep enough Mineral detail to separate a dark building from its surroundings.

## Composition

Keep the bay low and the sky open. In a landscape, distant water and shoreline usually sit around 70 to 80% of the canvas height. Mountains rise above that line. A tower can be taller than a mountain, so measure the quiet zone after quantising and inspect the actual headline area.

Tall posts preserve the complete scene across the bottom. Extend the sky instead of cropping away a bridge end, a roof or a boat. In this library the portrait scenery occupies roughly the bottom quarter to third. The square versions remove empty middle sky while retaining the upper right moon and the entire lower scene.

| Format | Canvas | Quiet zone |
| --- | --- | --- |
| Landscape post | 1600×900 | x 0, y 0, width 1600, height 468 |
| Portrait post | 1080×1350 | x 0, y 0, width 1080, height 756 |
| Square post | 1080×1080 | x 0, y 0, width 1080, height 562 |
| Scene master | 1920×1080 | Use the region recorded in the manifest. Post backgrounds guarantee the larger quiet region for each format |
| Header | 1500×500 | No type. Keep important subjects inside x 450 to 1450 and y 40 to 460 |

At least 97% of quiet zone pixels must use tones 0 and 1 by day, or tones 5 and 6 at night. The moon and sparse stars use part of the night allowance. A passing percentage does not make a busy local patch suitable for type. Inspect the headline's actual rectangle too.

For headers, x 0 to 420 and y 300 to 500 is the avatar exclusion. Water may fill it. Keep roofs, figures, arches, the doorway and lighthouse out. Nothing essential belongs in the top or bottom 40 pixels. The Pavilion header has the pavilion and bridge together. The Wallet header gives the pavilion more space. The Bridge header gives the complete ten arch crossing more space.

Two small people sit together at the pavilion. Their backs face the viewer. Their height is about 3 to 6% of a scene master and no more than about 9% of a shallow header. Keep two separate heads and bodies. Do not draw faces, merge the figures or add a crowd. The other places and all isolated vignettes have no people.

Environmental water, rocks and vegetation can continue through an image edge. Keep the whole subject intact: roof, columns, arch opening, doorway, hull and mast. Extend sky before making the final pixel grid. Blend joins in empty sky, then quantise the entire canvas once so the dither grid continues across the join.

## The seven tones

The index is part of the art pipeline. Use these exact RGB colours in this order. Pure black and pure white do not belong in art.

| Index | Colour | Day role | Night role |
| --- | --- | --- | --- |
| 0 | Paper #F4F2EC | Open sky, sunlit stone and small water marks | Moon edge, a few lit windows and the strongest stone and water reflections |
| 1 | #D9DFDF | Sky dither and faint clouds, light stone | Moon texture, softer window light and narrow reflections |
| 2 | #B8CAD1 | Pale cloud edges, far hills, distant water | Selected lit stone planes and softer reflection fragments |
| 3 | Mineral #8DB1C1 | Main water, hill planes and stone midtones | Moonlit water and readable middle planes of buildings |
| 4 | #7695A4 | Nearer hills, water depth, masonry shade | Muted masonry, near terrain and water detail |
| 5 | #57707F | Trees, arch shade and dark engraved texture | Sky dither, distant hills and subtle outlines inside dark planes |
| 6 | Ink #1B2B41 | Deep cuts, foreground silhouettes, outlines | Main sky, water shadow, foliage and deep architecture |

Clouds in a day quiet zone use mainly 0 and 1. Never fill the sky with 2 and 3 just to make the dither more visible. At night 5 and 6 do the quiet work. Use brighter tones for a reason, such as a moonlit edge, rather than scattering highlights over every surface.

Coral belongs to product errors and status notices. It never appears in the illustration. Product UI has its own token set; do not quantise a product card to this ramp.

## Pixel scale and dithering

Use pixel 1 at the native export dimensions for the social library, headers and vignettes. The 3000×1000 header is an exact nearest neighbour double of the 1500×500 file, giving a two pixel grid. The current sites' accepted day finals use pixel 1, while their older night bands use pixel 2.

The scale test compared day and night at pixels 1, 2 and 3, then reduced them to 600, 506 and 343 pixels and recompressed them as JPEG quality 85 with 4:2:0 chroma. Pixel 1 kept rails and stone joints clear. Pixel 2 and 3 made the night sky grainier. Pixel 3 also blunted the masonry. No large colour moiré appeared in the test; fine detail loss and patterned grain were the visible problems.

Native pixel 2 PNGs were smaller. Recompression reversed that benefit in the night examples: the 600 pixel night bay JPEG was 40,218 bytes at pixel 1 and 70,624 bytes at pixel 2. The night header was 27,281 and 43,871 bytes respectively. These are simulated processing results, not a statement about how X handles every upload.

See [the scale decision and images](../../qa/art/scale-test/DECISION.md). Full size tap images and 400% detail crops sit beside the feed comparisons.

At native pixel 1, the finest lines are one pixel wide. Most structural contours use one to three pixels; deeper shadow belongs in a plane rather than a thicker outline.

Use the existing blue-noise threshold map. Let short lines and material details carry the subject. Dither should connect neighbouring tones; it should not become a checkerboard over the whole picture. Reject smears, blotchy islands of texture and enlarged blocks that break an arch curve. Never blur a finished pixel image to hide a weak join.

## What never appears

| Exclusion | Reason |
| --- | --- |
| Smooth gradients, glow and neon | They replace the fixed tone and pixel structure with soft light effects |
| Photorealism and 3D renders | Their lighting and surface detail belong to another visual system |
| Modern objects | Phones, laptops, vehicles and contemporary street furniture break the setting. Show actual product UI separately |
| Coins, rockets, laser eyes, circuit boards and glowing cubes | They turn a specific Pavilion place into generic crypto imagery |
| Padlocks and chains | They imply a security promise and add a motif outside the accepted world. Use the strongroom door sparingly |
| Letters, numbers and marks that look like text | Generated writing is unreliable. Type and data belong in the layout |
| Faces and large portraits | The figures give the place a human scale. They are not characters or endorsers |
| Heavy clouds and dark blobs behind type | They break the quiet zone and reduce local readability |
| Invented arch counts, warped piers and ornate replacement rails | Repeated architecture identifies the place. An edit must preserve it |

The six files in assets/art/rejects/ have a reason in the manifest. Two are deliberate quantiser counterexamples: inversion and dense sky. Others show a mismatched old scene, coarse dither, an ornate replacement arch and a first doorway composition that missed the quiet zone test.

## How to make new art

### Edit the place first

1. Open the accepted raw and its final at full size. Inspect sky, horizon and detail crops at 400%. Count arches and figures. Record the features that must stay fixed.
2. Use the built-in image generation tool. Pass the raw PNG as the edit target. Change one thing at a time: lighting, sky extension, framing or an isolated subject.
3. Save every raw output in src/art/raw/brand-kit/. Record the exact prompt and source in src/art/PROMPTS.md. Keep failed attempts with descriptive names.
4. Compose to the target aspect ratio before quantising. Preserve the accepted lower scene when extending sky. Do not stretch the architecture or mirror the image.
5. Run the seven tone quantiser at the final dimensions. Tune the sky before adding stronger texture. Pack as an indexed PNG with exactly seven palette entries.
6. Check the final at 100%, at feed size and with its intended type. Fix a weak picture or leave it out of the library.

Existing day bay, pavilion and coast raws are the first references for those places. Night comes from those same day pictures. The doorway day comes from the accepted night courtyard. Generate from scratch only for a new isolated vignette or a subject without a source.

### Day scene prompt

Replace {place and locked features} with a plain inventory from the source. Keep the rest of the wording.

~~~text
Use case: precise-object-edit. Input image 1 is the EDIT TARGET, the accepted Pavilion raw. Preserve {place and locked features}, including every arch, roof, shoreline and figure. Recompose to a wide 16:9 social background with the complete scene in the lower 48 percent. Keep the upper 52 percent very pale Paper #F4F2EC sky with only faint offwhite cloud wisps. Daylight, Mineral #8DB1C1 water, Ink #1B2B41 engraved detail. Preserve exact fine Mediterranean square-pixel etched line work and patterned dither. Keep the whole subject visible. Do not mirror the scene or redesign its architecture. Strict Paper, Mineral and Ink with intermediate blue-grey dither tones. No text, letters, symbols, logos, signature, watermark, border, faces, extra people, modern objects, coins, rockets, laser eyes, circuit boards, padlocks, chains, glowing cubes, smooth gradients, glow, neon, photorealism or 3D.
~~~

### Night scene prompt

~~~text
Use case: lighting-weather. Input image 1 is the EDIT TARGET, the accepted Pavilion day raw. Preserve {place and locked features} at exactly the same positions and sizes, with the same arch count and figures. Change only the lighting to real moonlit night. Keep the upper 52 percent quiet Ink #1B2B41 sky with a few tiny stars and one small full moon at x 82%, y 20%, diameter 5% of canvas width. Put the moon inside the right third of the quiet zone. Dark Mineral water, a narrow broken Paper moon reflection, a few tiny lit windows and thin pale edges on moonlit stone. Preserve exact fine Mediterranean square-pixel engraving and patterned dither. Keep shadowed stone readable. No heavy cloud masses. Strict Paper #F4F2EC, Mineral #8DB1C1, Ink #1B2B41 and intermediate blue-grey dither tones. No text, letters, symbols, logos, signature, watermark, border, faces, extra people, modern objects, coins, rockets, laser eyes, circuit boards, padlocks, chains, glowing cubes, glow, beams, neon, smooth gradients, photorealism or 3D. Wide 16:9. Keep this recognisably the same place.
~~~

### Vignette prompt

Replace {subject} with one subject from the motif table. Use DAYLIGHT on perfectly flat Paper #F4F2EC or MOONLIGHT on perfectly flat Ink #1B2B41 for {lighting and surface}. For a night pair, pass the accepted day vignette as the edit target and preserve its geometry.

~~~text
Use case: stylized-concept. Asset type: isolated Pavilion vignette, square 1200x1200. Subject: {subject}. {lighting and surface}. Centre the complete subject within the central 68 percent with generous empty margins. Fine Direction A square-pixel engraved etching, material-following lines and small patterned dither. Use only Paper #F4F2EC, Mineral #8DB1C1, Ink #1B2B41 and their intermediate blue-grey dither tones. The outer ground or water patch dissolves through sparse square pixels into the perfectly flat background. No rectangular picture boundary, sky, horizon, stars or moon. Keep every roof, arch, door, hull and mast intact. No text, letters, symbols, logos, signature, watermark, border, faces, people, modern objects, coins, rockets, laser eyes, circuit boards, padlocks, chains, glowing cubes, smooth gradients, blur, glow, neon, photorealism or 3D.
~~~

### Quantiser commands

tools/pavilion_quantize.py is the unchanged source quantiser. It computes perceptual lightness, applies gamma, contrast and lift, then dithers through the blue-noise thresholds. The wrapper in src/art/quantize_art.py calls that same implementation, enforces the contract size and writes indexed pixels. Use it on an already composed raw at the correct aspect ratio.

| Kind | Native size | Pixel | Gamma | Contrast | Lift |
| --- | --- | ---: | ---: | ---: | ---: |
| Day scene | 1920×1080 | 1 | 0.92 | 1.08 | -0.035 |
| Night scene | 1920×1080 | 1 | 1.04 | 1.06 | 0.02 |
| Day background | 1600×900, 1080×1350 or 1080×1080 | 1 | 0.92 | 1.08 | -0.035 |
| Night background | Same three formats | 1 | 1.04 | 1.06 | 0.02 |
| Day header | 1500×500 | 1 | 0.92 | 1.08 | -0.035 |
| Night header | 1500×500 | 1 | 1.04 | 1.06 | 0.02 |
| Day vignette | 1200×1200, exact Paper border | 1 | 0.92 | 1.08 | -0.035 |
| Night vignette | 1200×1200, exact Ink border | 1 | 1.04 | 1.06 | 0.02 |

~~~sh
uv run --with pillow --with numpy python3 -I tools/pavilion_quantize.py composed-day.png day-preview.png --width 1600 --pixel 1 --tones 7 --gamma 0.92 --contrast 1.08 --lift -0.035
uv run --with pillow --with numpy python3 -I src/art/quantize_art.py composed-day.png day.png --width 1600 --height 900 --pixel 1 --gamma 0.92 --contrast 1.08 --lift -0.035
uv run --with pillow --with numpy python3 -I src/art/quantize_art.py composed-night.png night.png --width 1600 --height 900 --pixel 1 --gamma 1.04 --contrast 1.06 --lift 0.02
~~~

For another kind, substitute its width and height from the table. Make the 3000×1000 header with nearest neighbour from the approved 1500×500 file. Do not quantise that copy again.

For vignettes, build_vignettes.py scales the raw into a 1008×1008 inset on the 1200×1200 surface, normalises near-background pixels to the exact surface colour and checks the outer 64 pixels. build_formats.py assembles all three backgrounds and header doubles. build_rejects.py trims palette padding to exactly seven entries and updates byte counts. These builders reproduce this library; a new subject also needs a manifest entry and source prompt.

~~~sh
uv run --with pillow --with numpy python3 -I src/art/build_scenes.py
uv run --with pillow --with numpy python3 -I src/art/build_vignettes.py
uv run --with pillow --with numpy python3 -I src/art/build_formats.py
uv run --with pillow --with numpy python3 -I src/art/build_rejects.py
uv run --with pillow --with numpy python3 -I src/art/check_art.py
~~~

### QA before approval

- Confirm PNG mode P, the exact seven palette entries, dimensions and source paths against the manifest.
- Measure the 97% quiet zone rule and the moon's position. Inspect the actual type rectangle as well.
- Count arches in day and night. Check straight piers, complete arches, roof joins and terrace rails.
- Check two separate figures at the pavilion, with no faces. Check every other scene for accidental people.
- Reject marks that look like text, modern objects, smooth shading, glow, smeared dither, sky seams and dark blobs.
- Open every final at native size and 343 pixels. Use the 600 and 506 pixel compression tests for detailed backgrounds and headers.
- Put web and mobile avatar circles over each header. Confirm every 2× file is an exact nearest neighbour double.
- Check vignette edges on an exact Paper or Ink surface. A pale square around a night subject is a failed export.

Keep status draft until every required file exists and the checks and visual review pass. The manifest records an honest alt description, source raw and prompt for every item. Teaching rejects remain labelled as rejects.

## Export for X

The kit's upload masters are indexed PNGs: 1600×900 landscape, 1080×1350 portrait, 1080×1080 square, 1500×500 headers and their 3000×1000 doubles. Scenes are 1920×1080; vignettes are 1200×1200 assets for layouts. The palette contains exactly the seven ramp entries and no transparency.

Keep a finished file at its native dimensions. Make a larger copy only at whole-number scale with nearest neighbour. Do not repeatedly resize, blur, sharpen or save an upload master as JPEG. Feed-size reductions and JPEGs in the evidence folder test damage a service may introduce; they are not production exports.

Select the background made for the format. Do not centre-crop the 16:9 bridge into a portrait post. Add concise alt text that names the place and useful objects. If the post's image contains type, its alt text should also include that message.

## Type and product UI on art

Put headlines in the manifest's quiet region. Use Ink type on a day background and Paper on a night background. Keep the left 60% clear of the moon. Leave room below the last line before the first roof or hill. Move the text or change the background when a local cloud or highlight interferes.

Use Manrope for the headline, body and lockup. Use Geist Mono only for actual data. Keep logos, type and diagrams as crisp vector or native layout layers. Never generate lettering inside the picture, dither a wordmark or apply pixel effects to a product card.

Place a real product module on its opaque product surface, using the same dimensions and tokens as the product. It can overlap the lower art on the right if it does not hide the picture's identifying subject. Keep the doorway, pavilion roof or bridge's main span readable. Show only the necessary UI, at a size that can be read at feed width.

Type, UI and art are separate layers until the post is exported. Export the composition once. The art library itself stays free of copy and product screens.