# Haitian Editorial Illustrations Specification

**Conformance target:** A family of warm, transparent, 2D editorial illustrations that depicts dignified contemporary Black Haitian adults, familiar objects, and concrete actions as one coherent mobile product system

**Status:** Draft specification. The visual family is approved as a style reference, but production conformance remains pending target-user comprehension testing, in-market review, and rights confirmation.

**Audience:** Designers, illustrators, researchers, engineers, and generative-image workflows producing onboarding art, empty states, trust cues, account states, savings concepts, and instructional moments for Haitian mobile products

**Scope:** Character-led and object-led raster illustrations for square mobile placements, delivered as transparent PNG files. The style supports single actors, small groups, gesture close-ups, status portraits, and compact place anchors.

**Companion specs:** `equity/design-for-low-literacy-spec.mdx`, `equity/bias-audit-spec.mdx`, `equity/gender-bias-spec.mdx`, `equity/financial-concept-framing-spec.mdx`, `regions/Haiti-spec.mdx`, `accessibility/WCAG-AA-spec.mdx`, `visual/visual-language-spec.mdx`

**Implementation home:** The visually approved Sòl reference set lives in `apps/mobile/public/illustrations/haiti-flat/`. Its `README.md` records the current assets, prompts, output details, and comprehension-testing status.

**Decision provenance:** On 2026-08-20, the product owner rejected a monochrome 3D isometric pass because it did not match the supplied character reference. The approved direction is warm 2D editorial character art. This specification records that decision and the measurable properties of the visually approved reference set.

**Evidence record:**

- **E1, visual direction decision:** Product owner review, 2026-08-20. The supplied character reference replaced the earlier 3D isometric specification as visual authority. The product owner then approved the revised PNG family as "really good."
- **E2, measured reference family:** 18 generated PNG assets measured on 2026-08-20 by the design workflow. All are 1024 by 1024 RGBA files; alpha bounds, coverage, file size, palette, and edge conditions are machine-checkable with `rosca/scripts/validate-haiti-flat.py`. The stable review artifact is `illustrations/haitian-editorial-reference-v1.png`, SHA-256 `01d94d57f65c50c3602810e847631158384e15c0fb6a4d78da6618bc60e55607`.
- **E3, low-literacy evidence:** `equity/design-for-low-literacy-spec.mdx`, including Medhi et al. on concrete visual carriers, unlabeled testing, and audio equivalence.
- **E4, Haiti market evidence:** `regions/Haiti-spec.mdx`, including Haitian Creole, rural connectivity, outdoor use, local color associations, offline assets, and in-market testing.
- **E5, representation and framing evidence:** `equity/bias-audit-spec.mdx`, `equity/gender-bias-spec.mdx`, and `equity/financial-concept-framing-spec.mdx`.
- **E6, accessibility floor:** `accessibility/WCAG-AA-spec.mdx`, including non-text contrast, text alternatives, and redundant state cues.

Terms **MUST**, **SHOULD**, and **MAY** follow [RFC 2119](https://www.rfc-editor.org/rfc/rfc2119).

**The core claim:** this style earns trust through human action, not decoration. Each illustration shows a dignified person, gesture, object, or compact group doing one concrete thing that a user can name before reading a label. Cultural fit, semantic clarity, anatomy, palette, scale, and transparent-edge quality are all acceptance gates.

**Out of scope:** 3D isometric art, monochrome object families, photorealism, stickers, emoji, heavy-outline cartoons, scenic posters, full marketing environments, animation, data visualization, and interface icons intended below 64 CSS pixels.

---

## 1. Purpose and conventions

| Field | Content |
|---|---|
| **Rule** | Every illustration MUST have one written target read, one user job, and named wrong reads before visual production begins. The image MUST be accepted on semantic clarity before style polish. |
| **Why** | An attractive image that reads as "finance" instead of "saving money in a circle" does not help a low-literacy user. The image is part of the product language, so the intended read must be testable. [E3, E4] |
| **How to verify** | Show the image alone to a reviewer who has not seen the brief. Record their first description. It must match the target read and avoid every named wrong read. |

Each section below uses the same Field/Content format and lists **MUST / SHOULD / MAY** rules. The unit of work is one **illustration**: one canvas, one concept, and one validated target read.

**MUST**

- Record the target concept in English and Haitian Creole.
- Record the intended product moment, such as onboarding, verification, error, or empty state.
- Record at least two plausible wrong reads.
- State whether the illustration is meaningful or decorative at its point of use.

**MUST NOT**

- Begin from a generic mood such as "trustworthy" or "joyful" without a concrete action or state.
- Accept the author's own interpretation as proof that the image reads correctly.

---

## 2. Core visual grammar

| Field | Content |
|---|---|
| **Rule** | The artwork MUST read as warm 2D editorial illustration: organic silhouettes, rounded anatomy, restrained internal detail, earthy colors, subtle plane shading, and no separate heavy-outline system. |
| **Why** | These properties are what make the visually approved reference set feel human, contemporary, and cohesive. Changing any one asset to geometric icon art, 3D rendering, or photorealism breaks the family immediately. [E1, E2] |
| **How to verify** | Review the new asset in a grid with at least six visual-reference assets at 160 CSS pixels. A reviewer must not be able to identify the new asset by a different rendering method, outline system, texture density, or level of realism. |

**MUST**

- Use filled organic shapes as the primary construction method.
- Keep anatomy and objects softly rounded rather than mechanically geometric.
- Use darkened local color for internal seams and facial detail.
- Keep the image grounded in one readable action or state.
- Preserve a calm, dignified editorial tone even for error and offline states.

**SHOULD**

- Let overlapping forms and value changes create depth.
- Keep the artwork legible when facial detail and texture disappear at small size.
- Use one consistent visual-density band across a product flow.

**MUST NOT**

- Use uniform black keylines around every shape.
- Use glossy 3D bevels, metallic rendering, rim lighting, or dramatic studio shadows.
- Render a subject as a sticker, mascot, emoji, clip-art symbol, or logo.
- Add decorative confetti, sparkles, floating dots, or abstract blobs to fill empty space.

---

## 3. Semantic construction

| Field | Content |
|---|---|
| **Rule** | Every illustration MUST communicate meaning through one literal actor-plus-action or object-plus-state relationship. Meaning MUST NOT depend on text, color alone, facial expression alone, or a sequence inferred from reading direction. |
| **Why** | Concrete actions outperform abstract symbols for users with limited reading experience. A person placing a coin in a vessel is more direct than a generic upward arrow, and a phone with a broken signal is more direct than a disconnected-cloud metaphor. [E3, E4] |
| **How to verify** | Name the actor, action, object, and state. At least two of these must be visually explicit, and the target read must survive when all labels are covered. |

**MUST**

- Show the critical action at the largest useful scale.
- Use one dominant semantic relationship.
- Make state markers singular and large: one check, one X, one lock, one clock, or one broken signal.
- Keep security, error, and financial states paired with visible product copy in the interface.
- Keep the action cue visually separate from hair, clothing patterns, and canvas edges.

**SHOULD**

- Prefer actions drawn from daily practice over symbolic financial tropes.
- Use a familiar object when it carries the concept more clearly than a full person.
- Use the fewest supporting props that preserve the read.

**MUST NOT**

- Use color as the only state difference.
- Use a facial expression as the only error, success, or waiting cue.
- Show several equally weighted actions.
- Use arrows when a handoff, movement, or gesture can show the action directly.
- Assume a Western metaphor is locally understood.

---

## 4. Composition archetypes

| Field | Content |
|---|---|
| **Rule** | Every illustration MUST use one of five composition archetypes and MUST keep one clear visual center. Archetype choice is flexible by concept, but scale, margin, rendering vocabulary, and small-size readability remain controlled. |
| **Why** | A small number of composition types lets the family cover people, objects, groups, and places without becoming a collage of unrelated layouts. [E1, E2] |
| **How to verify** | Name the archetype in the asset record and point to the visual center. If two centers compete or the asset does not fit one archetype, revise the composition. |

### 4.1 Gesture close-up

One or two hands plus one object or gesture. Use for handshake, share, lock, identification, password, and draw-a-circle concepts.

**MUST**

- Keep the hand action anatomically plausible.
- Keep the semantic object unobstructed.
- End cropped arms at a clean sleeve boundary, never at a wrist or finger joint.

### 4.2 Single-actor action

One full or partial adult visibly acting on one primary prop. Use for verification, savings, error, offline, waiting, and similar flows.

**MUST**

- Show the action through hands, posture, and prop placement.
- Keep the prop large enough to read at 96 CSS pixels.
- Keep the actor and prop as one compact silhouette.

### 4.3 Status portrait

A head-and-shoulders or waist-up portrait with one large state marker. Use for verified profile and identity states.

**MUST**

- Keep the marker subordinate to the person but large enough to read.
- Place the marker where it does not cover the face.
- Avoid medallions, seals, or award framing unless the concept requires them.

### 4.4 Group interaction

Three or four equally scaled adults showing one shared relationship. Use for celebration, queue, circle, and community concepts.

**MUST**

- Keep every person at equal social scale.
- Make the relationship topology clear through spacing, gaze, hands, or orientation.
- Limit the group to four people unless a larger crowd is explicitly required and tested.

### 4.5 Anchored place

One actor plus one familiar place anchor, such as a masonry home or wooden gate.

**MUST**

- Keep the place compact and subordinate to the concept.
- Omit horizon, sky, road scene, and unrelated environmental detail.
- Limit plants and secondary environmental cues to two simple masses.

**MUST NOT**

- Use a full room, street, village panorama, or scenic landscape.
- Mix archetypes to create a poster-like scene.

### 4.6 Camera and perspective

The family uses an editorial near-orthographic viewpoint rather than a photographic lens effect.

**MUST**

- Keep people between a front view and a restrained three-quarter view.
- Keep vertical structural lines parallel.
- Keep object top-plane visibility below roughly 25 degrees.
- Keep faces, hands, and phones close to their natural relative scale except for the permitted hand enlargement.
- Omit a horizon line and visible camera tilt.

**SHOULD**

- Use eye-level framing for people.
- Use a slight elevated view for hand-and-object close-ups when it improves recognition.
- Keep depth compression similar across a group.

**MUST NOT**

- Use isometric projection, fisheye distortion, extreme foreshortening, dramatic low angles, bird's-eye views, or cinematic depth of field.

---

## 5. Canvas, scale, and alignment

| Field | Content |
|---|---|
| **Rule** | Deliver every asset on a 1024 by 1024 pixel transparent canvas. The longest nonzero-alpha artwork bound MUST be 720 to 800 pixels, and the artwork center MUST remain within 8 pixels of canvas center. |
| **Why** | The assets ship in square mobile slots. Normalized occupancy prevents one concept from feeling more important because it was rendered larger, and the clear perimeter lets the image sit naturally on a card or page. [E2] |
| **How to verify** | Compute the alpha bounding box. Confirm the longest axis is 720 to 800 pixels, no nonzero-alpha pixel touches the canvas edge, and the box center differs from canvas center by no more than 8 pixels per axis. |

The visually approved 2026-08-20 reference set uses a maximum 800 pixel artwork dimension. Its measured visible coverage ranges from roughly 11% to 34% because a wide handshake and a full seated figure occupy different shapes. Coverage percentage is therefore archetype-dependent and is not a fixed requirement.

**MUST**

- Use an 8-bit RGBA PNG.
- Keep all four corners fully transparent.
- Preserve at least 112 transparent pixels on each side of the longest artwork axis.
- Keep the composition complete. A close-up MAY crop at a deliberate sleeve or torso boundary.
- Pad rather than stretch when normalizing scale.

**SHOULD**

- Keep the visual center near the geometric center.
- Keep paired assets at similar visual weight.
- Use high-quality Lanczos or equivalent downsampling.

**MUST NOT**

- Crop a hand, face, semantic marker, foot, or object by accident.
- Let any nonzero-alpha pixel touch the canvas boundary.
- Enlarge a small source after generation if the resulting detail becomes visibly soft.

---

## 6. Character anatomy and pose

| Field | Content |
|---|---|
| **Rule** | Human anatomy MUST be stylized but structurally plausible. Poses MUST communicate action without exaggerated cartoon distortion. |
| **Why** | Hands, faces, and device grips are the first features users notice and the most common generative failure points. Anatomical errors damage trust even when the concept is otherwise clear. [E1, E2] |
| **How to verify** | Inspect every face, hand, joint, grip, and overlap at 200% zoom. Then inspect the full pose at 96 CSS pixels. Reject any fused finger, broken wrist, duplicate limb, floating prop, or impossible weight balance. |

**MUST**

- Keep adult figures approximately 5.5 to 7.5 head heights tall.
- Keep shoulders, elbows, wrists, hips, knees, and ankles connected plausibly.
- Show five fingers when all fingers are visible.
- Keep a phone or card seated naturally inside the hand.
- Keep standing figures balanced over their feet.
- Keep seated figures visibly supported by the stool or chair.

**SHOULD**

- Enlarge hands by no more than about 25% when gesture readability requires it.
- Build hair as a few organic masses rather than individual strands.
- Use rounded limbs and garments with broad, simple folds.
- Keep expressions warm, calm, and restrained.

**MUST NOT**

- Exaggerate eyes, lips, noses, hips, or musculature as a shortcut to expressiveness.
- Use victory poses for routine financial states.
- Depict panic, shame, or blame in error states.
- Use infantilized proportions for adults.

---

## 7. Faces, hair, and identity

| Field | Content |
|---|---|
| **Rule** | People MUST read as varied Black Haitian adults without turning any one hairstyle, garment, accessory, or face into mandatory shorthand for Haitian identity. |
| **Why** | Representation becomes stereotype when the same cues are repeated as a costume. The family needs recognizable cultural grounding and meaningful variation at the same time. [E5] |
| **How to verify** | Review the full library as a group. Count repeated hairstyles, accessories, roles, body shapes, and gender presentations. No single cue should appear so often that removing it would make the set stop reading as Haitian. |

**MUST**

- Use credible natural hair forms, including coils, afros, buns, short textured cuts, braids, and wraps.
- Vary facial structure, skin tone, hair, body shape, age presentation, and clothing across the library.
- Keep skin as a tonal range rather than one required swatch.
- Keep expressions dignified and context-appropriate.
- Review gender and role distribution across the full set.

**SHOULD**

- Include a mix of women and men as actors, organizers, helpers, recipients, and decision-makers.
- Include older adults where the concept and research support it.
- Vary gold jewelry and headwrap use rather than applying them to every woman.

**MUST NOT**

- Require a headwrap, hoop earrings, patterned skirt, or straw hat in every asset.
- Make women passive recipients while men perform all technical or financial actions.
- Use facial caricature or skin-lightening.
- Infer a person's economic status from skin tone, clothing color, or hairstyle.

### 7.1 Facial-detail levels

**MUST**

- Use no facial detail in gesture close-ups that do not show a face.
- Keep a single actor or status portrait to three to seven facial feature groups: brows, eyes, nose, mouth, and optional cheek or ear marks.
- Keep each person in a group to two to five facial feature groups.
- Preserve identity through silhouette, hair, face shape, and posture before adding small features.

**SHOULD**

- Let minor facial marks disappear at 96 CSS pixels while the expression and head direction remain legible.
- Keep teeth, eyelashes, nostrils, and individual hair strands absent unless the concept cannot read without them.

### 7.2 Textile-pattern grammar

**MUST**

- Keep patterns clipped cleanly inside the garment plane.
- Use simple geometric, leaf, dot, or block motifs with no text, flag, logo, or religious symbol.
- Keep motifs approximately 24 to 64 source pixels across.
- Keep garment-pattern contrast below the contrast of the action cue and face.

**SHOULD**

- Use no more than one dominant pattern per person.
- Use no more than two pattern families in a group composition.
- Let patterns disappear before garment silhouette, anatomy, or gesture does.

**MUST NOT**

- Use high-frequency micro-patterns, photorealistic textile weave, or patterns that continue incorrectly across folds and body overlaps.

---

## 8. Rural Haitian localization

| Field | Content |
|---|---|
| **Rule** | Rural Haitian cues MUST be contemporary, familiar, and relevant to the action. They MUST NOT frame rural life as primitive, broken, helpless, or outside modern services. |
| **Why** | The target user may live in a rural area and still use smartphones, identification, mobile services, organized savings, and modern clothing. Rural localization should increase recognition, not stage poverty. [E4, E5] |
| **How to verify** | For every local cue, state what comprehension work it performs. Remove any cue that exists only to make the image appear more "Haitian" or more "rural." Review the set with someone from the target market. |

Valid candidate cues include:

- Masonry homes with corrugated roofs
- Wooden gates and stools
- Woven baskets
- Clay vessels and calabash-inspired forms
- Practical long skirts, shirts, trousers, and simple shoes
- Straw hats and headwraps used selectively
- Natural hair
- Broad-leaf vegetation used sparingly
- Smartphones, identity cards, and modern service objects

**MUST**

- Keep clothing clean, intact, practical, and contemporary.
- Show agency, reciprocity, and equal status in giving or sharing scenes.
- Use local material cues only when they support recognition.
- Treat every culturally specific metaphor as a testable hypothesis.

**MUST NOT**

- Use torn clothing, barefoot helplessness, begging, disaster framing, charity hierarchy, or poverty spectacle.
- Use flags as a shortcut for cultural identity.
- Use Vodou symbols as decorative motifs or generic Haitian shorthand.
- Use gambling, luck, jackpot, or sudden-wealth imagery for savings concepts.
- Present smartphones or formal identity as foreign to rural users.

---

## 9. Palette system

| Field | Content |
|---|---|
| **Rule** | Use the measured earthy palette below as a role-based family. Skin, fabric, wood, clay, and devices MAY vary tonally, but major fills SHOULD remain close to the anchor colors and MUST preserve the warm overall balance. |
| **Why** | The restricted palette is the strongest family signal after anatomy. Cool blues, neon accents, or unrelated pastels make a new asset look imported from another library. [E2, E4] |
| **How to verify** | Quantize the visual-reference raster and compare dominant fills to the anchors. Major fills SHOULD remain within Delta E 00 of 12 from an anchor. Highlights and shadows MAY extend to 20 if the material still reads correctly. |

Measured anchors from the visually approved 2026-08-20 reference set:

| Role | Anchor colors | Use |
|---|---|---|
| Charcoal | `#1C1D1B` | Hair, shoes, phones, strongest internal structure |
| Deep green | `#354629`, `#445630`, `#526339` | Trust, stability, secondary clothing, doors, foliage |
| Burnt orange | `#C3450D`, `#CC4D12`, `#D35D15` | Action, energy, primary clothing, error marker |
| Mustard | `#E3860B` | Warmth, celebration, small positive accents |
| Warm cream | `#EAC58B`, `#F9E2BE` | Shirts, screens, highlights, neutral surfaces |
| Wood and clay | `#C8862C` | Baskets, stools, gates, vessels, house detail |
| Skin shadow | `#5E2E0F` | Deep skin shadow and overlap |
| Skin midtone | `#874114` | Common skin body tone |
| Skin highlight | `#A45D1E` | Lit skin plane |

Computed contrast against app cream `#F4F1DE`:

| Color | Contrast |
|---|---|
| Charcoal `#1C1D1B` | 14.89:1 |
| Skin highlight `#A45D1E` | 4.44:1 |
| Skin midtone `#874114` | 6.61:1 |
| Skin shadow `#5E2E0F` | 9.87:1 |
| Deep green base `#445630` | 7.06:1 |
| Deep green light `#526339` | 5.77:1 |
| Burnt orange base `#CC4D12` | 3.99:1 |
| Burnt orange light `#D35D15` | 3.46:1 |
| Mustard `#E3860B` | 2.41:1 |
| Wood and clay `#C8862C` | 2.68:1 |
| Warm cream `#F9E2BE` | 1.11:1 |

**MUST**

- Keep silhouette-defining shapes at 3:1 or stronger against the approved background.
- Contain mustard, wood, clay, and cream shapes inside darker forms when they carry meaning.
- Keep state differences distinguishable by shape as well as hue.
- Keep skin tonal variation natural and coherent within one figure.

The current `draw-a-circle.png` visual reference does not meet the first rule: its yellow semantic stroke is approximately 1.56:1 against app cream. It MUST be darkened or reinforced before production acceptance. It remains in the visual reference only for composition, gesture, and rendering style.

**SHOULD**

- Use orange and mustard for energy and positive warmth.
- Use green for trust, stability, and supporting structure.
- Use charcoal sparingly for high-contrast detail.
- Keep the number of major garment colors to three per asset.

**MUST NOT**

- Add neon, electric blue, cool cyan, bright violet, or unrelated pastel fills.
- Change skin tone to satisfy palette balance.
- Use red or orange alone to communicate error.
- Use Haitian flag colors as a decorative palette.

---

## 10. Shading, contours, and texture

| Field | Content |
|---|---|
| **Rule** | Forms SHOULD use two to four broad tonal planes with restrained soft transitions. Edges SHOULD come from value separation and darkened local color, not a uniform outline. |
| **Why** | The visual-reference set is flatter than painted art but softer than vector iconography. Broad planes keep it readable at mobile size while subtle transitions preserve warmth and humanity. [E1, E2] |
| **How to verify** | Downscale the image to 128 CSS pixels. Major forms must remain distinct. At 200% zoom, shading must remain broad and quiet, with no glossy streaks, hard gradient bands, or noisy texture. |

**MUST**

- Keep lighting coherent within one illustration.
- Use darkened local color for facial marks, garment seams, and object detail.
- Keep critical internal marks approximately 3 to 8 source pixels wide.
- Keep the outer silhouette readable without a separate outline layer.

**SHOULD**

- Use two to four tonal planes per major material.
- Keep texture low-contrast enough to disappear before the silhouette does.
- Use a small amount of broad texture for wood, clay, hair, or woven baskets.
- Keep cast shadows absent or extremely soft and local.

**MUST NOT**

- Use uniform black outlines.
- Use strong drop shadows, glows, sticker borders, or rim lights.
- Use photorealistic skin pores, fabric weave, scratches, or wood grain.
- Use glossy phone reflections or metallic highlights that shift the asset toward 3D rendering.

### 10.1 Family light model

**MUST**

- Use one broad diffuse light source from the upper-left quadrant.
- Place primary highlights on upper and left-facing planes.
- Place the darkest local shadows under overlaps and on lower-right planes.
- Keep the face and action cue at least as legible as surrounding clothing.

**SHOULD**

- Keep adjacent broad planes about 8 to 25 luminance points apart.
- Reserve stronger value jumps for deep overlap, hair, device edges, and critical symbols.
- Keep the light direction visually consistent across a contact sheet.

**MUST NOT**

- Use backlighting, colored light, spotlights, dramatic cast shadows, or a different light direction for decorative effect.

---

## 11. Symbols, devices, and text

| Field | Content |
|---|---|
| **Rule** | Devices and status symbols MUST be simplified, large, and free of readable text. A symbol MAY reinforce meaning but MUST NOT replace the concrete human or object relationship when that relationship is required. |
| **Why** | Tiny generated interfaces produce gibberish, do not localize, and disappear at mobile size. Large singular symbols survive scaling and remain language-independent. [E3, E6] |
| **How to verify** | Inspect at 96 CSS pixels. A state marker MUST span at least 4.5% of the illustration slot, which is 4.3 CSS pixels at that review size, with a minimum effective stroke of 1.25 CSS pixels and 3:1 contrast against its immediate field. If the marker is the sole signal, it MUST be at least 12 CSS pixels across. |

**MUST**

- Use one large check, X, lock, clock, or broken signal.
- Keep phone screens to one state marker and at most four geometric password dots.
- Keep identification fields as blank bars and a portrait silhouette.
- Keep devices structurally plausible and free of brand marks.
- Keep coins plain and free of foreign currency symbols.
- Render status-bearing illustrations at no less than 160 CSS pixels in the product.

**MUST NOT**

- Render words, letters, digits, barcodes, QR codes, carrier names, or logos.
- Render fake user-interface copy.
- Use several competing symbols.
- Use a dollar sign or foreign currency glyph.
- Use a symbol so small that the concept depends on the caption.

---

## 12. Transparency and surface behavior

| Field | Content |
|---|---|
| **Rule** | Final files MUST use true alpha transparency with no baked checkerboard, matte rectangle, panel, horizon, or full-canvas background. The approved placement is a warm light surface. |
| **Why** | These assets must sit naturally inside the app without looking like rectangular pictures. Background-removal defects become obvious on tinted surfaces and can make an otherwise polished image look unfinished. [E2, E6] |
| **How to verify** | Read the PNG metadata, inspect the alpha channel, and composite the asset at 100% on white, app cream `#F4F1DE`, deep teal `#264653`, and black. Cream and white are approval surfaces. Teal and black are diagnostic surfaces for halos and edge contamination. |

**MUST**

- Deliver an RGBA PNG with a real alpha channel.
- Keep all corners at zero alpha.
- Show no fringe wider than 1 CSS pixel at intended display size.
- Remove cyan, green, red, white, or gray matte contamination from edge pixels.

**SHOULD**

- Use straight-alpha output.
- Set RGB to zero in fully transparent pixels before final export.
- Inspect hair, sleeves, hands, plant leaves, roof edges, and circular strokes at 100% zoom.
- Keep semi-transparent pixels below 20% of all nonzero-alpha pixels. A higher ratio triggers manual mask review.

**MUST NOT**

- Bake a checkerboard into the image.
- Place the approved light-surface asset directly on a dark page.
- Use CSS inversion, global tinting, or a generic white outline to create a dark variant.

### 12.1 Dark surfaces

The current palette is not dark-surface safe. Charcoal, skin shadows, and greens lose separation on ink or black.

**MUST**

- Place the illustration inside a warm cream container on a dark surface, or author and test a separate dark-surface variant.

**MUST NOT**

- Claim dark-mode support based only on file transparency.

---

## 13. Generative production workflow

| Field | Content |
|---|---|
| **Rule** | Generation MUST follow a reproducible sequence: semantic brief, archetype, prompt, candidate review, background cleanup, scale normalization, grid review, technical validation, and comprehension testing. |
| **Why** | A generative model has no memory of the visual-reference family. Consistency lives in the brief, reference grid, prompt record, cleanup process, and rejection criteria. [E2] |
| **How to verify** | Select any production-accepted asset. Its record must contain every stage, the exact prompt, tool, reference source, post-processing method, review score, and comprehension result. |

### 13.1 Brief

Record:

- Target user
- User job
- Target read in English and Haitian Creole
- Named wrong reads
- Ethical and positioning non-goals
- Composition archetype
- Hero, action, and state marker
- Required and prohibited cultural cues

### 13.2 Prompt

Every prompt MUST restate the frozen style properties. Do not rely on chat history or model memory.

Canonical prompt template:

```text
Create a polished standalone mobile-app illustration of [SUBJECT AND ACTION].
Use warm 2D editorial flat art with dignified contemporary Black Haitian adults,
natural hair, rounded plausible anatomy, organic silhouettes, restrained internal
detail, subtle broad-plane shading, and an earthy palette of burnt orange, mustard,
deep green, warm cream, dark brown skin tones, wood and clay, and charcoal. Use
[COMPOSITION ARCHETYPE] with one concrete action or state and one clear visual
center. Keep the complete composition compact and readable at 96 CSS pixels.
No photorealism, 3D isometric rendering, geometric icon treatment, heavy uniform
outlines, sticker border, scenery, frame, caption, text, digits, currency symbol,
flag, logo, watermark, gambling cue, charity hierarchy, or poverty spectacle.
Render on [TRUE ALPHA OR APPROVED SOLID KEY COLOR] with no checkerboard pattern.
```

### 13.3 Reference boundary

**MUST**

- Use `illustrations/haitian-editorial-reference-v1.png` as the primary visual-family reference and verify its recorded SHA-256 before use.
- Treat the contact sheet as a rendering reference only. It does not establish semantic, accessibility, cultural, or production acceptance for every depicted asset.
- Confirm that any external visual reference is licensed or supplied with permission for the intended use.
- Describe the style in this specification's own terms.
- Record the reference source and review date.

**MUST NOT**

- Name or imitate a living artist.
- Trace, reconstruct, or copy a third-party composition.
- Treat a reference image as a license.

---

## 14. Background removal and edge cleanup

| Field | Content |
|---|---|
| **Rule** | If the generator cannot create true alpha, use one documented key color that does not appear in the artwork, then remove it with color decontamination and boundary repair before normalization. |
| **Why** | Generic background removal produced white and cyan halos in the first visual-reference iterations. Hair, hands, clothing, roofs, and circle strokes need controlled edge cleanup rather than a simple transparency threshold. [E2] |
| **How to verify** | Composite the native 1024 pixel output on cream, white, deep teal, and black. Inspect at 100%. Run the edge-color predicate and confirm zero key-colored boundary pixels remain. |

The 2026-08-20 pipeline used solid cyan `#00FFFF` because cyan is prohibited in the artwork palette.

### 14.1 Keying baseline

For source RGB pixel `P` and cyan key `K = [0, 255, 255]`:

```text
D = EuclideanDistance(P, K)
alpha = clamp((D - 16) / 84, 0, 1)
```

Force alpha to zero when:

```text
R < 45 and G > 205 and B > 205
```

These thresholds are a recorded baseline, not a universal constant. A new generator or key color requires a new calibration.

### 14.2 Boundary decontamination

The alpha boundary is every visible pixel whose alpha is below 255 or whose 8-connected neighborhood contains at least one zero-alpha pixel. Spatial distance is Euclidean distance in source-pixel coordinates.

Define a cyan-like pixel as:

```text
G > 1.12 * R + 8
B > 1.12 * R + 8
abs(G - B) < 95
G > 70
B > 70
```

Within 24 source pixels of the alpha boundary:

- Replace cyan-like opaque and semi-transparent RGB values with the nearest safe interior artwork color.
- Define a safe interior pixel as alpha at least 220 and not cyan-like.
- Preserve the original alpha value.
- Set alpha values below 6 to zero.
- Break equal-distance ties by highest alpha, then lowest source y coordinate, then lowest source x coordinate.
- If no safe interior pixel exists within 24 pixels, use the median safe color from the same connected artwork component.
- If the component has no safe interior pixel, stop and require manual mask repair.

**MUST**

- Recompute the boundary test after cleanup.
- Reach zero remaining key-like boundary pixels with alpha at least 16 under the calibrated predicate.
- Report lower-alpha key-like pixels as diagnostics because they are visually negligible but may indicate mask drift.
- Inspect thin strokes separately because they may have no wide interior region.
- Complete edge cleanup before scale normalization.

**MUST NOT**

- Remove a halo by hard-thresholding the whole alpha channel.
- Erase hair, foliage, fingers, garment hems, or chalk strokes to create a cleaner silhouette.
- Leave key-colored RGB in fully opaque boundary pixels.

---

## 15. Output and delivery

| Field | Content |
|---|---|
| **Rule** | The shipped asset MUST be a losslessly optimized 1024 by 1024 RGBA PNG authored for sRGB, named mechanically, with reproducible provenance and no draft files in the delivery directory. |
| **Why** | Raster output is the approved source format for this generative style. A consistent delivery contract prevents background loss, accidental JPEG conversion, filename drift, and silent replacement by rejected drafts. [E2] |
| **How to verify** | Validate dimensions, color mode, alpha, bounds, filename, file size, and manifest entry from a clean checkout. Render the shipped file, not the generation preview. |

**MUST**

- Use lowercase kebab-case filenames.
- Use `.png`.
- Preserve 8-bit RGBA. Embed an sRGB profile or leave the file untagged for standard browser sRGB interpretation.
- Keep the longest artwork bound at 720 to 800 pixels.
- Keep each asset below 550 KB after lossless optimization unless documented visual quality requires more.
- Keep the implementation directory free of SVG, JPEG, and rejected alternatives.
- Record a checksum after production acceptance.

**SHOULD**

- Keep the full set below 8 MB.
- Load only the illustration required by the current screen.
- Keep generation sources and review renders outside the shipped directory.

**MUST NOT**

- Convert to JPEG.
- Flatten transparency onto white or cream.
- Hand-edit only the shipped PNG without recording and reproducing the edit.
- Replace a production-accepted file without rerunning the complete review gate.

### 15.1 Automated validation

Run from the Sòl repository root:

```bash
uv run --python 3.11 --with pillow --with numpy \
  python scripts/validate-haiti-flat.py
```

The bitmap validator checks count, filename format, file type, 1024 pixel canvas, RGBA mode, sRGB policy, alpha bounds, outer margins, center offset, edge contact, corner alpha, visible cyan contamination, semi-transparent-pixel ratio, file size, and SHA-256. It returns a nonzero exit code for blocking defects and emits warnings for manual mask review. Manifest completeness, visual scoring, cultural review, live rendering, rights, and comprehension remain separate human gates.

---

## 16. Accessibility and product integration

| Field | Content |
|---|---|
| **Rule** | Every meaningful illustration MUST have accessible text and visible product copy at its point of use. Decorative illustrations MUST be hidden from assistive technology. |
| **Why** | The image supports comprehension but cannot carry every nuance, error recovery step, or security consequence. Screen-reader users need equivalent meaning, while duplicate decorative announcements create noise. [E3, E4, E6] |
| **How to verify** | Inspect the rendered surface. A meaningful image has concise alt text and adjacent visible copy. A decorative image has empty alt text and does not receive focus. |

**MUST**

- Pair every meaningful image with visible text in the user's language.
- Provide offline Haitian Creole audio for every text-bearing screen that uses an illustration.
- Use concise action-oriented alt text when the image carries unique meaning.
- Use `alt=""` when adjacent text already communicates the same meaning.
- Keep illustrations non-interactive unless the entire image is inside a labeled control.
- Preserve readability under font scaling and responsive layout.

**SHOULD**

- Prefer pre-recorded or pre-generated audio over streamed runtime speech.
- Keep primary app illustrations between 96 and 240 CSS pixels.
- Use the icon system below 64 CSS pixels.

**MUST NOT**

- Put essential instructions inside the raster.
- Make the illustration the only warning for a financial, security, destructive, or irreversible action.
- Use alt text that describes clothing and appearance while omitting the action.

---

## 17. Review and acceptance

| Field | Content |
|---|---|
| **Rule** | An asset is accepted only after semantic, visual-family, cultural, anatomy, technical, live-render, and comprehension gates pass. A blocking defect overrides the numeric score. |
| **Why** | Each gate catches a different failure. A clean alpha mask does not prove comprehension, and a culturally grounded concept does not excuse malformed hands. [E2, E3, E4] |
| **How to verify** | Complete the rubric and attach the unlabeled-review phrases, technical report, contact sheets, live browser screenshot, and target-user comprehension result. |

### 17.1 Review sizes and surfaces

**MUST**

- Review at 96, 128, and 160 CSS pixels.
- Inspect at native 1024 pixel resolution.
- Review the full family in one grid.
- Composite on white, app cream, deep teal, and black.
- Treat deep teal and black as diagnostic halo surfaces, not approved placements.
- Capture a fresh browser screenshot of the shipped file.

### 17.2 Weighted visual rubric

| Dimension | Weight |
|---|---|
| Target concept read | 30 |
| Family fidelity | 20 |
| Rural Haitian cultural fit | 15 |
| Anatomy and gesture | 10 |
| Palette, shading, and edges | 10 |
| Composition and scale | 10 |
| Alpha, format, and output quality | 5 |

Score every dimension from 0 to 5, then multiply by its weight:

- **5:** Exact family fit with no observable defect
- **4:** Minor defect with no semantic or small-size impact
- **3:** Clear defect that requires revision
- **2:** Major defect that weakens the concept or family fit
- **1:** Severe defect with only partial usable content
- **0:** Missing, wrong, or unusable

For each dimension, calculate `rating / 5 * weight`, then sum the weighted values. A score of 90 to 100 passes visual review if no blocker exists. A score of 80 to 89 requires revision. A score below 80 is rejected.

**MUST**

- Score at least 90 out of 100.
- Have no blocking defect.
- Use at least one reviewer who did not see the prompt.
- Record the score and reviewer reasoning.

The Sòl reference set received a 94 out of 100 visual-only review score on 2026-08-20. The product owner separately approved its appearance. Because the historical score predates this rubric's recorded breakdown and no target-user comprehension test has occurred, it is not a production-conformance score.

### 17.3 Comprehension gate

**MUST**

- Test each new concept without its label with at least five target users.
- Record the first response in the participant's own words.
- Reach at least 80% correct identification.
- Revise or reject any concept below 80%.

**SHOULD**

- Test high-risk security, money, error, and identity states with at least ten users and target 90%.
- Test in the actual deployment context and on the target device.
- Compare plausible metaphor variants rather than asking whether one image is "clear."

**MUST NOT**

- Claim low-literacy compliance before this gate passes.
- Coach participants or reveal the label before recording the first read.

---

## 18. Blocking rejection conditions

Reject an asset immediately if any of the following is present:

- Opaque or baked background
- Checkerboard rendered as pixels
- Key-color or white fringe
- Nonzero-alpha pixel touching the canvas edge
- Target concept unreadable at 96 CSS pixels
- Text-like gibberish, digits, currency symbols, logos, or flags
- Fused fingers, duplicate limbs, malformed faces, warped phones, or floating props
- Heavy uniform outlines
- Photorealistic, isometric, sticker, or geometric icon treatment
- Neon or cool off-palette color
- Several competing actions or state markers
- Charity hierarchy, poverty spectacle, caricature, or stereotype-dependent meaning
- Gambling, jackpot, luck, or sudden-wealth framing
- Unapproved dark-surface placement
- Visual score below 90
- Comprehension below the required threshold

---

## 19. Governance and extending the family

| Field | Content |
|---|---|
| **Rule** | Every addition MUST be reviewed against the visual-reference family and recorded in the implementation manifest. Changes to a frozen property require a versioned style decision, not a one-off exception. |
| **Why** | Illustration systems drift one asset at a time. A new rendering model, palette, anatomy style, or cleanup method can quietly split one family into several. [E2] |
| **How to verify** | Pick any production-accepted asset. Its record must identify the concept, archetype, exact prompt, generator, reference, cleanup process, technical checks, review score, comprehension result, date, and owner. |

Required manifest fields:

- Filename
- Target concept in English
- Target concept in Haitian Creole
- Product moment
- Target read
- Named wrong reads
- Composition archetype
- Prompt
- Generator and exposed model identifier
- Reference source and rights status
- Generation date
- Cleanup method and thresholds
- Canvas dimensions and alpha bounds
- File size and checksum
- Visual review score
- Reviewer names or roles
- Comprehension sample and score
- Status: draft, visual-pass, comprehension-pass, or shipped
- Owner

**MUST**

- Review additions in a grid with the visual-reference family.
- Re-run every technical and visual check after replacement or optimization.
- Date every change to a frozen property.
- Keep the implementation README focused on asset records and link back to this specification.

**MUST NOT**

- Add an asset because it looks acceptable in isolation.
- Silently switch generation tools, models, key colors, cleanup algorithms, or output profiles.
- Treat one approved character design as the mandatory face of every Haitian user.

---

## 20. Current open risks

The following are known open risks, not approved exceptions:

1. The current 18 assets have passed visual and technical review but not target-user comprehension testing.
2. `empty-mailbox` is a requested concept but a weak rural-Haiti metaphor because physical mail is not broadly familiar.
3. `draw-a-circle.png` uses a low-contrast yellow semantic stroke and requires remediation before production use.
4. The current files are light-surface assets. No dark-surface family has been authored.
5. The implementation README is a transitional record and does not yet contain every manifest field required by section 19.
6. No reviewer from the target Haitian market has approved this specification, as required before finalizing a spec that affects equity.
7. Generative anatomy and alpha cleanup remain process risks even when a prior asset passed.
8. A user-provided visual reference does not establish publication rights. Rights must be confirmed before external distribution.

---

*Specification version: 1.0. Decision date: 2026-08-20.*