Visual Baseline

Visual Baseline

Review the default RNUI visual language in one place — typography, controls, elevated surfaces, and status treatments. Use this page after token or component changes to confirm nothing regressed.

RNUI Design Foundation Contract

Source of truth: .planning/rnui-design-foundation-contract.md

Layer	Rule
Surfaces	Fill + border required; shadow optional depth only
Borders	default for shells, input for fields, subtle for dividers — all perceptible
Radius	lg buttons/inputs, xl cards/modals — not pill-by-default
Shadow	Soft mobile-native elevation; no Bootstrap black slabs
Status	bg + border + text on every severity
States	Focus, disabled, pressed, selected use semantic tokens

Native example app is the source of truth — CSS previews below approximate tokens. Run the SurfaceVisibility screen in apps/example after token changes.

Automated guardrail: bun run build && bun run surface:audit

Component family checklist

Family	Pass criteria
Layout (Card, Paper, Divider)	Visible with shadow.none
Actions (Button, Toggle)	Outline/ghost/disabled readable
Forms (Input, FormGroup)	Visible inside Card
Status (Badge, Alert, Toast)	bg + border + text
Overlay (Modal, Menu, Select)	Panel border + fill
Data (List, Table, Tabs)	Row/tab separation without shadow-only

Typography

Hierarchy should feel mobile-native: clear steps without overpowering body copy.

Type scale

Display through caption in a realistic content block

Design systems that feel native

RNUI pairs semantic tokens with polished components so your product reads consistently on iOS and Android without reinventing spacing, color, or type on every screen.

Why teams choose RNUI

Ship faster with accessible defaults, subtle elevation, and motion that respects reduced-motion preferences.

Updated 2 days ago · 4 min read

Buttons

Default radius is rounded-lg (not pill). Solid actions stay premium with soft elevation; outline and ghost stay lightweight.

Button variants

Hero card plus solid · outline · ghost · destructive

Upgrade to Pro

Unlock offline mode, shared workspaces, and priority support for your team.

Start free trialLearn more

Variants

PrimaryOutlineGhostDelete

Input

Native-friendly 44px height (aligned with Button md), soft borders, and readable placeholder text.

Profile form

Label, helper text, and error state

Sign in

EmailWe’ll never share your email.PasswordInvite codeThis code has expired.Continue

Card & Paper

Elevated surfaces use subtle border + soft shadow — border and fill must remain visible with shadow disabled (see No-shadow section below).

Settings card

Realistic profile / product layout

Alex Morgan

Product designer · San Francisco. Usually replies within a few hours.

MessageView profile

Weekly summary

12 tasks completed · 3 meetings · Focus time up 18% from last week.

Badges

Every variant includes background, border, and text so pills read on normal app backgrounds.

Badge variants

default · brand · accent · success · warning · error · info

On app background

ShippedDelayedFailedIn transit

Orders

#1042 — Studio deskDelivered

#1041 — Monitor armProcessing

#1040 — Cable kitDraft

Account

SubscriptionPro

SecurityAction needed

All variants

DefaultBrandAccentSuccessWarningErrorInfo

Chips, alerts, toast & controls

Status surfaces stay refined — elevated toast and snackbar cards (not heavy inverse slabs). Alerts use severity borders on standard variant.

Feedback & toggles

Chips, alerts, toast, snackbar, switch, and checkbox

Chips

ProductDraftFilterLive

New version available

Update to 2.4 for faster sync and improved offline mode.

Payment method expiring

Your card ends in 12 days. Update billing to avoid interruption.

✓

Profile saved

Your changes are live across all devices.

!

Could not upload photo

Check your connection and try again.

Changes savedUndo

Controls

Push notificationsMarketing emails✓Remember this deviceShare analytics

Visible surface test

Status components must be visible without relying on iOS glass, blur, notification-shade blending, or dark overlays.

Visibility matrix

Badges, chips, and compact alerts on five surfaces

White surface

DefaultBrandAccentSuccessWarningErrorInfo

BrandNeutralActive

Synced

Failed

App background

DefaultBrandAccentSuccessWarningErrorInfo

BrandNeutralActive

Synced

Failed

Card surface

DefaultBrandAccentSuccessWarningErrorInfo

BrandNeutralActive

Synced

Failed

Glass surface

DefaultBrandAccentSuccessWarningErrorInfo

BrandNeutralActive

Synced

Failed

Dark surface

DefaultBrandAccentSuccessWarningErrorInfo

BrandNeutralActive

Synced

Failed

Rules

1. Background — status fill must differ from the surface behind it
2. Border — 1px semantic border defines the edge
3. Text — semantic text color stays readable (WCAG AA on the fill)
4. No blur dependency — if a badge only looks correct over glass, the tokens are wrong

Surfaces tested

Surface	Token reference
White	#FFFFFF
App background	color.bg.default
Card	color.surface.raised
Glass	color.glass.surface
Dark	color.surface.default (dark)

Native overlay QA

CSS demos above approximate tokens — overlays must be verified in the example app on iOS and Android.

Example app screens

Component	Example screen	Native checks
Modal	apps/example/app/components/Modal.tsx	Inset, safe area, keyboard form, animation
Dialog	Dialog.tsx	Host inset, actions slot, form input
AlertDialog	AlertDialog.tsx	Destructive confirm, button layout
Alert	Alert.tsx	Compound title + body severity colors

Run: cd apps/example && bun run ios (or android). Full checklist: Example app guide.

Device checklist (summary)

Light + dark on iPhone-sized simulator and one Android emulator:

1. Modal/Dialog never flush to screen edges (host inset visible)
2. Form-in-modal: primary action stays above keyboard (iOS)
3. Alert title + body share severity hue without manual color props
4. Toast action label readable; Snackbar uses elevated surface
5. Badge default and accent readable on app background
6. Backdrop tap and hardware back dismiss where onClose is set

Repo copy: .planning/device-qa-checklist.md

No-shadow surface visibility test

Components must remain visible when shadow/elevation is disabled. Shadow may add depth but must never be required for recognition.

No-shadow matrix

Card, Paper, Badge, Chip, Alert, Input, and outline/ghost/disabled buttons — shadow stripped

App background

Card · shadow none

Paper · elevation none

DefaultSuccessError

SolidOutlined

Info alert

Visible without shadow.

Email

OutlineGhostDisabled

Card surface

Card · shadow none

Paper · elevation none

DefaultSuccessError

SolidOutlined

Info alert

Visible without shadow.

Email

OutlineGhostDisabled

White surface

Card · shadow none

Paper · elevation none

DefaultSuccessError

SolidOutlined

Info alert

Visible without shadow.

Email

OutlineGhostDisabled

Glass surface

Card · shadow none

Paper · elevation none

DefaultSuccessError

SolidOutlined

Info alert

Visible without shadow.

Email

OutlineGhostDisabled

Dark surface

DefaultSuccessError

SolidOutlined

Info alert

Visible without shadow.

What to verify

Component	No-shadow check
Card	White fill + border.default on bg.default
Paper	Border + fill at elevation none
Badge / Chip	Fill + border on app, card, and glass panels
Alert	Severity bg + 1px border
Input	surface.default fill + border.input
Button outline/ghost	Border or brand text — not shadow-dependent
Disabled	Reduced opacity but still readable

Test backgrounds

• App background (color.bg.default)
• White / card surface (color.surface.default / raised)
• Glass-like panel (color.surface.glass)
• Dark panel (color.bg.inverse or dark surface.default)

Native QA: example app screen SurfaceVisibility — full A–G matrix (neutral, form, status, action, data, overlay notes, dark panel) with real RNUI components.

Surface Visibility Contract

Hard rules enforced by tokens, component recipes, and bun run surface:audit:

1. Fill first — component background must differ from the parent canvas (bg.default, surface.default, or surface.raised) without relying on shadow.
2. Border required — 1px semantic border (border.default, border.input, or status border) must remain perceivable on light and dark surfaces.
3. Shadow is optional depth — shadow.sm and up may enhance elevation; removing shadow must not hide the component.
4. Status triple — Badge, Chip, Alert, Toast variants need background + border + text on app, white, card, glass, and dark panels.
5. Nested surfaces — Card-on-Card uses surface.raised inner fill; FormGroup grouped uses outer border; Input keeps border.input inside Card.
6. Glass fallback — translucent fills (surface.glass) pair with visible surface.glassBorder.
7. Brand themes — bg.default and surface.default must not collapse; borders strengthened per brand tint.

Reference docs: .planning/surface-visibility-contract.md · audit: scripts/audit-surface-contrast.mjs

Final truth is the native example app — CSS demos approximate tokens; run SurfaceVisibility on iOS/Android simulators after token changes.

Related

• Example app — native QA workflow
• Modal · Dialog · Alert
• Badge — order and account demos
• Button — full API reference
• Card — elevated surface patterns