Design System: The Tactile Sanctuary for Neurodiversity

ComuniTEA’s design system is named The Tactile Sanctuary — a philosophy that deliberately rejects the sterile, clinical aesthetic common in medical and educational software. Instead of rigid grids and harsh dividers, it creates a digital environment that feels like a premium physical object: stacked sheets of warm, organic paper. Every decision prioritizes cognitive ease for children with Autism Spectrum Disorder (ASD) and AAC needs, while maintaining a high-end editorial quality that respects both the child’s intelligence and the caregiver’s need for a serene, predictable interface. The system is codified in constants/Colors.ts, constants/Theme.ts, and DESIGN.md.

Color System

Base Surfaces

The palette is rooted in earth tones designed to reduce visual overstimulation. The UI is treated as a series of physical layers — stacked sheets of heavy, warm paper — rather than a flat grid.

// constants/Colors.ts — baseSurface
const baseSurface = {
  surface:                '#f8f4e3',  // Base screen (Linen)
  surfaceContainerLow:    '#f2eedc',  // Large content areas
  surfaceContainerLowest: '#ffffff',  // Top-layer cards (max lift)
  surfaceContainerHigh:   '#ebe8da',  // Hover / tap feedback
  surfaceContainerHighest:'#e6e3d2',  // Focus layer

  onSurface: '#1d1c12',              // Warm near-black — never pure black
  tertiary:  '#506074',              // Slate blue for icon strokes
  secondaryContainer: '#fdc5b5',     // Safe Space Drawer background
  border: 'rgba(29, 28, 18, 0.12)', // Soft contextual border

  danger:  '#b85c52',
  success: '#5a7a62',
  warning: '#c9a227',
}

The “No-Line” Rule: 1px solid borders are explicitly prohibited for sectioning. Boundaries must be defined solely through background color shifts or tonal transitions. If a border is absolutely required for accessibility, use outlineVariant at 15% opacity maximum — never 100% opaque.

Theme Palettes

ComuniTEA ships three complete color themes, each sharing the base surfaces but swapping the primary action color. The active theme is controlled by the appThemeStore (Zustand) and accessed via the useThemeColors() hook.

// constants/Colors.ts — Palettes
export const Palettes = {
  sage: {
    primary:          '#a4c3b2',  // Muted sage green
    primaryDark:      '#83a391',
    primaryLight:     '#d2e1d9',
    primaryContainer: '#cce0d5',
    onPrimary:        '#1d1c12',
    accent:           '#eab4a4',  // Pale red accent
    header: {
      background: '#a4c3b2',
      text:       '#1d1c12',
      badge:      '#ffffff',
    }
  },
  rojo: {
    primary:          '#eab4a4',  // Warm rose
    primaryDark:      '#c99383',
    primaryLight:     '#f5dad3',
    primaryContainer: '#f0c8bc',
    onPrimary:        '#1d1c12',
    accent:           '#a4c3b2',  // Sage green accent
    header: {
      background: '#eab4a4',
      text:       '#1d1c12',
      badge:      '#ffffff',
    }
  },
  azul: {
    primary:          '#37475a',  // Slate blue
    primaryDark:      '#232e3b',
    primaryLight:     '#5c6b7d',
    primaryContainer: '#4a5c70',
    onPrimary:        '#ffffff',  // White text on dark primary
    accent:           '#eab4a4',  // Pale red accent
    header: {
      background: '#37475a',
      text:       '#ffffff',
      badge:      '#a4c3b2',
    }
  }
}

Sage

Muted sage green primary (#a4c3b2). The default theme. Calming, nature-inspired, with warm rose as the accent. Header uses dark text on the green background.

Rojo

Warm rose primary (#eab4a4). Soft and warm. Uses sage green as the accent color. Ideal for users who respond positively to warm tones.

Azul

Deep slate blue primary (#37475a). The most contrast-rich theme. Uses white onPrimary text, making it suitable for users who benefit from higher contrast.

Category Colors

Each AAC vocabulary category has its own dedicated color for quick visual identification. These are part of baseSurface and remain consistent across all three themes:

// constants/Colors.ts — category color map
category: {
  acciones:   '#c17f3a',  // Amber orange
  comida:     '#c45c3a',  // Burnt orange
  emociones:  '#c9a227',  // Golden yellow
  personas:   '#b85c7a',  // Rose pink
  lugares:    '#3d8a7a',  // Teal
  objetos:    '#506074',  // Slate grey-blue
  yo:         '#a4c3b2',  // Sage green
  bano:       '#4a8fab',  // Sky blue
  dormir:     '#6b5a8a',  // Muted purple
  jugar:      '#5a7a62',  // Forest green
  ropa:       '#8a5a8f',  // Mauve
  quiero:     '#c45c3a',  // Burnt orange
  'no-quiero':'#b85c52',  // Muted red
  default:    '#6b6f72',  // Neutral grey
}

Roundedness Scale

Rounded corners are the most distinctive visual signature of The Tactile Sanctuary. Sharp 0px corners are prohibited in the main UI. The scale maps to numeric pixel values in React Native:

// constants/Theme.ts — Radii
export const Radii = {
  sm:      8,     // 0.5rem — inside nested elements
  default: 16,    // 1rem   — small cards
  md:      24,    // 1.5rem — standard cards, AAC chips
  lg:      32,    // 2rem   — main containers and sections
  xl:      48,    // 3rem   — buttons and hero elements
  full:    9999,  // pill   — chips, search bars, tags
} as const;

Token	px	rem equivalent	Typical usage
`sm`	8	0.5rem	Nested elements, inner chips
`default`	16	1rem	Small cards
`md`	24	1.5rem	Standard cards, AAC chips
`lg`	32	2rem	Main containers, sections
`xl`	48	3rem	Buttons, hero elements
`full`	9999	—	Pills, chips, search bars

Spacing Scale

The Space token exported from constants/Theme.ts defines consistent padding and gap values used across all components. Using these tokens — rather than ad-hoc pixel values — ensures that the rhythm of white space remains uniform and predictable, which is a primary navigation aid for ASD users.

// constants/Theme.ts — Space
export const Space = {
  xs:  4,   // Tight internal padding (e.g., icon-to-label gap)
  sm:  8,   // Standard internal padding
  md:  16,  // Component padding, list item gap
  lg:  24,  // Section gap, card-to-card spacing
  xl:  32,  // Large section breaks
  xxl: 40,  // Screen-level vertical rhythm
} as const;

Token	px	Typical usage
`xs`	4	Icon-to-label gap, tight internal padding
`sm`	8	Standard internal padding, input inset
`md`	16	Component padding, list item gap
`lg`	24	Section spacing, card-to-card gap
`xl`	32	Large section breaks
`xxl`	40	Screen-level vertical rhythm

Elevation and Shadow System

Traditional drop shadows are too visually noisy for children with sensory sensitivities. The Tactile Sanctuary uses ambient light principles — depth is achieved by stacking surface tiers, not by adding visible shadows.

// constants/Theme.ts — Shadow tokens
const ON_SURFACE = '#1d1c12';

export const ShadowAmbient = {
  shadowColor:   ON_SURFACE,       // Warm tinted black, never pure #000
  shadowOffset:  { width: 0, height: 10 },
  shadowOpacity: Platform.OS === 'android' ? 0.06 : 0.05,
  shadowRadius:  28,
  elevation:     3,
} as const;

export const ShadowAmbientLight = {
  shadowColor:   ON_SURFACE,
  shadowOffset:  { width: 0, height: 4 },
  shadowOpacity: 0.04,             // 4% — barely perceptible
  shadowRadius:  20,
  elevation:     2,
} as const;

ShadowAmbient — used for floating elements that need a perceptible lift (e.g., the Sentence Strip, modal sheets). Blur of 28px, opacity 5–6%.
ShadowAmbientLight — used for cards and standard UI elements. Blur of 20px, opacity 4%.
Shadow color is always the warm near-black #1d1c12 (the onSurface token), never pure #000000, so the shadow carries a warm tint consistent with the overall palette.

The ghost border utility provides a barely-visible stroke when an explicit border is required for accessibility:

// constants/Theme.ts
export const outlineBorder = (width = 1) => ({
  borderWidth: width,
  borderColor: 'rgba(29, 28, 18, 0.15)',  // ~15% opacity
});

Typography

ComuniTEA uses a curated two-font pairing loaded via @expo-google-fonts, both included as direct dependencies in package.json:

"@expo-google-fonts/plus-jakarta-sans": "^0.4.2",
"@expo-google-fonts/be-vietnam-pro": "^0.4.1"

Role	Font	Rationale
Display / Headings	Plus Jakarta Sans	Geometric, open counters. “Authoritative yet kind.” Used for large welcoming greetings and milestone screens.
Body / Labels	Be Vietnam Pro	Exceptional legibility at small sizes — critical for AAC pictogram labels and instructional text.

Both fonts feature open counters and rounded terminals that reinforce the friendly, approachable character of the brand while remaining highly legible for AAC users.

Use display-lg (equivalent to ~3.5rem) sparingly. Large display text should overlap slightly with surface containers to break the standard boxy layout and create an editorial, layered feel. This intentional asymmetry is a core design principle.

Component Guidelines

Buttons

Primary buttons use a gradient fill and extreme rounding to give them physical weight:

Background: Linear gradient from primary → primaryContainer at 135°
Border radius: xl (48px / 3rem)
Padding: ~1.5rem × 2.5rem
Press state: Scale down to 0.98 + increase shadow density to simulate physical depression
Secondary buttons: Use surfaceContainerHighest fill with primary text — no border

AAC Communication Chips

The core interactive element of the app — pictogram buttons on the communication board:

Border radius: md (24px / 1.5rem), or full (9999px) for pill-shaped chips
Background: surfaceContainerLowest (#ffffff)
Icon safe zone: 16px minimum padding around pictograms
Icon color: tertiary (#506074) for strokes to maintain Slate Blue softness
Interaction: surfaceContainerHigh on tap for gentle, unambiguous feedback

Cards and Lists

No divider lines. Never use horizontal rules or borderBottom between list items.
Spacing only: Use md (1.5rem / 24px) or lg (2rem / 32px) vertical spacing to separate items.
Hover/tap state: Transition background to surfaceContainerHigh (#ebe8da) for clear but gentle feedback.

The Safe Space Drawer

A unique signature component — a bottom-sheet drawer for calming tools and break timers:

Background: secondaryContainer (#fdc5b5) — a warm, soft rose
Backdrop blur: Heavy (20px), using Glassmorphism: surface colors at ~80% opacity
Border radius: xl (48px) top corners only
Purpose: Houses calming activities, timers, or sensory break tools. The warm rose color is intentionally distinct from the main surface hierarchy to signal a safe, low-stakes zone.

// The secondaryContainer token
secondaryContainer: '#fdc5b5',  // Warm rose — Safe Space Drawer

Theme Switching

The active theme is managed by a Zustand store (appThemeStore) and can be 'sage', 'rojo', or 'azul'. Colors are synchronized to the static Colors export via syncStaticColors():

// constants/Colors.ts
export type ThemeColor = 'sage' | 'rojo' | 'azul';

export function syncStaticColors(theme: ThemeColor) {
    const s = Palettes[theme];
    (Object.keys(s) as (keyof AppColorPalette)[]).forEach((k) => {
        if (k === 'text' || k === 'header' || k === 'category') return;
        (Colors as Record<string, unknown>)[k as string] = s[k] as unknown;
    });
    Object.assign(Colors.text.logo, s.text.logo);
    Object.assign(Colors.text, { ...s.text, logo: Colors.text.logo });
    Object.assign(Colors.header, s.header);
    Object.assign(Colors.category, s.category);
}

In components, always consume colors through useThemeColors() (or the reactive palette from the store) rather than importing Colors directly. This ensures your component re-renders when the caregiver switches themes.

Animation Guidelines

All motion in ComuniTEA must feel heavy and organic, never snappy or robotic. This is a sensory consideration: rapid or linear animations can be distressing for children with ASD.

Spring-based transitions only. Use react-native-reanimated’s spring configurations for all interactive feedback (press, mount, dismiss).
AnimationIntensity control: The app exposes an AnimationIntensity setting so caregivers can reduce motion for users with sensory sensitivities. Respect this setting in all animated components.
Scale on press: 0.98 (not 0.95 or lower) — subtle depression, not a dramatic collapse.
Avoid: Linear easing, bounce easing with high overshoot, or any transition under 150ms.

Do not use pure #000000 black anywhere in the UI. Always use onSurface (#1d1c12) or tertiary (#506074) for text and strokes. Pure black creates visual “vibration” against the warm cream surfaces, which can be visually uncomfortable for ASD users.

Data & State

Feature Modules

Development

Design System: The Tactile Sanctuary for Neurodiversity

Color System

Base Surfaces

Theme Palettes

Sage

Rojo

Azul

Category Colors

Roundedness Scale

Spacing Scale

Elevation and Shadow System

Typography

Component Guidelines

Buttons

AAC Communication Chips

Cards and Lists

The Safe Space Drawer

Theme Switching

Animation Guidelines

Build docs developers (and LLMs) love

Data & State

Feature Modules

Development

Documentation Index

​Color System

​Base Surfaces

​Theme Palettes

Sage

Rojo

Azul

​Category Colors

​Roundedness Scale

​Spacing Scale

​Elevation and Shadow System

​Typography

​Component Guidelines

​Buttons

​AAC Communication Chips

​Cards and Lists

​The Safe Space Drawer

​Theme Switching

​Animation Guidelines

Build docs developers (and LLMs) love

Color System

Base Surfaces

Theme Palettes

Category Colors

Roundedness Scale

Spacing Scale

Elevation and Shadow System

Typography

Component Guidelines

Buttons

AAC Communication Chips

Cards and Lists

The Safe Space Drawer

Theme Switching

Animation Guidelines