visual consistency
+ interaction consistency
+ accessibility consistency
+ composition consistency
+ migration consistency

<AppThemeProvider mode="dark" density="compact" dir="rtl">
  <FormField name="email" error="Email is required">
    <Label>Email</Label>
    <Input />
    <FieldError />
  </FormField>
</AppThemeProvider>

<Input
  id="email"
  aria-describedby="email-error"
  aria-invalid={true}
  density="compact"
  dir="rtl"
  colorMode="dark"
/>

Environment context = "komponen hidup di lingkungan apa?"
Structural context  = "komponen ini bagian dari struktur apa?"
Capability context  = "komponen ini boleh meminta apa?"

// Bad smell
<AppContext value={{
  theme,
  density,
  user,
  permissions,
  selectedRows,
  modalState,
  openModal,
  formErrors,
  currentTab,
  queryResult,
}}>
  {children}
</AppContext>

props + state + context -> UI

Good context:
  Button membaca density dari DesignSystemProvider.

Bad context:
  Button membaca currentInvoice dari AppContext.

Provider scope harus sekecil mungkin, tapi sebesar yang diperlukan.

<ThemeContext value={{
  colors: hugeColorObject,
  spacing: hugeSpacingObject,
  typography: hugeTypographyObject,
  mode,
  setMode,
}}>

:root {
  --ds-color-bg: white;
  --ds-color-fg: black;
  --ds-radius-md: 8px;
}

[data-theme="dark"] {
  --ds-color-bg: #0b0b0f;
  --ds-color-fg: #f5f5f5;
}

import { createContext, useContext, useMemo, useState } from 'react';

type ThemeMode = 'light' | 'dark' | 'system';
type ResolvedTheme = 'light' | 'dark';

type ThemeContextValue = {
  mode: ThemeMode;
  resolvedTheme: ResolvedTheme;
  setMode: (mode: ThemeMode) => void;
};

const ThemeContext = createContext<ThemeContextValue | null>(null);

export function ThemeProvider({ children }: { children: React.ReactNode }) {
  const [mode, setMode] = useState<ThemeMode>('system');

  // Simplified. Real implementation would subscribe to prefers-color-scheme.
  const resolvedTheme: ResolvedTheme = mode === 'system' ? 'light' : mode;

  const value = useMemo(
    () => ({ mode, resolvedTheme, setMode }),
    [mode, resolvedTheme]
  );

  return (
    <ThemeContext value={value}>
      <div data-theme={resolvedTheme}>{children}</div>
    </ThemeContext>
  );
}

export function useTheme() {
  const value = useContext(ThemeContext);
  if (!value) {
    throw new Error('useTheme must be used inside ThemeProvider');
  }
  return value;
}

// Often unnecessary
function Button() {
  const { resolvedTheme } = useTheme();
  return <button className={resolvedTheme === 'dark' ? 'darkBtn' : 'lightBtn'} />;
}

// Better for many visual concerns
function Button(props: ButtonProps) {
  return <button className="ds-button" {...props} />;
}

comfortable -> spacing besar, mudah dibaca
compact     -> spacing kecil, cocok data-dense admin UI

<DensityProvider value="compact">
  <CaseTable />
</DensityProvider>

<DensityProvider value="comfortable">
  <CaseSummaryCard />
</DensityProvider>

type Density = 'comfortable' | 'compact';

const DensityContext = createContext<Density>('comfortable');

export function DensityProvider({
  value,
  children,
}: {
  value: Density;
  children: React.ReactNode;
}) {
  return (
    <DensityContext value={value}>
      <div data-density={value}>{children}</div>
    </DensityContext>
  );
}

export function useDensity() {
  return useContext(DensityContext);
}

[data-density="comfortable"] {
  --ds-control-height: 40px;
  --ds-control-padding-x: 12px;
}

[data-density="compact"] {
  --ds-control-height: 32px;
  --ds-control-padding-x: 8px;
}

.ds-input {
  min-height: var(--ds-control-height);
  padding-inline: var(--ds-control-padding-x);
}

function DataGridVirtualizer() {
  const density = useDensity();
  const estimatedRowHeight = density === 'compact' ? 32 : 44;

  return <VirtualizedTable estimatedRowHeight={estimatedRowHeight} />;
}

Visual adaptation -> CSS variables / data attributes.
Behavioral adaptation -> Context read boleh dipakai.

type Direction = 'ltr' | 'rtl';

const DirectionContext = createContext<Direction>('ltr');

export function DirectionProvider({
  dir,
  children,
}: {
  dir: Direction;
  children: React.ReactNode;
}) {
  return (
    <DirectionContext value={dir}>
      <div dir={dir}>{children}</div>
    </DirectionContext>
  );
}

export function useDirection() {
  return useContext(DirectionContext);
}

function getHorizontalIntent(event: KeyboardEvent, dir: 'ltr' | 'rtl') {
  if (event.key === 'ArrowRight') {
    return dir === 'rtl' ? 'previous' : 'next';
  }

  if (event.key === 'ArrowLeft') {
    return dir === 'rtl' ? 'next' : 'previous';
  }

  return null;
}

<label htmlFor="email">Email</label>
<input id="email" aria-describedby="email-hint email-error" aria-invalid="true" />
<p id="email-hint">Use your work email.</p>
<p id="email-error">Email is required.</p>

import { createContext, useContext, useId, useMemo } from 'react';

type FieldContextValue = {
  id: string;
  name?: string;
  labelId: string;
  descriptionId: string;
  errorId: string;
  invalid: boolean;
  required: boolean;
  disabled: boolean;
  describedBy: string | undefined;
};

const FieldContext = createContext<FieldContextValue | null>(null);

export function Field({
  id: explicitId,
  name,
  error,
  required = false,
  disabled = false,
  children,
}: {
  id?: string;
  name?: string;
  error?: string;
  required?: boolean;
  disabled?: boolean;
  children: React.ReactNode;
}) {
  const generatedId = useId();
  const id = explicitId ?? generatedId;
  const invalid = Boolean(error);

  const labelId = `${id}-label`;
  const descriptionId = `${id}-description`;
  const errorId = `${id}-error`;

  const describedBy = invalid
    ? `${descriptionId} ${errorId}`
    : descriptionId;

  const value = useMemo(
    () => ({
      id,
      name,
      labelId,
      descriptionId,
      errorId,
      invalid,
      required,
      disabled,
      describedBy,
    }),
    [id, name, labelId, descriptionId, errorId, invalid, required, disabled, describedBy]
  );

  return <FieldContext value={value}>{children}</FieldContext>;
}

export function useFieldContext(componentName: string) {
  const value = useContext(FieldContext);
  if (!value) {
    throw new Error(`${componentName} must be used inside <Field>`);
  }
  return value;
}

export function Label({ children }: { children: React.ReactNode }) {
  const field = useFieldContext('Label');

  return (
    <label id={field.labelId} htmlFor={field.id}>
      {children}
      {field.required ? <span aria-hidden="true"> *</span> : null}
    </label>
  );
}

export function Input(props: React.InputHTMLAttributes<HTMLInputElement>) {
  const field = useFieldContext('Input');

  return (
    <input
      {...props}
      id={field.id}
      name={props.name ?? field.name}
      disabled={props.disabled ?? field.disabled}
      required={props.required ?? field.required}
      aria-labelledby={field.labelId}
      aria-describedby={field.describedBy}
      aria-invalid={field.invalid || undefined}
    />
  );
}

export function FieldDescription({ children }: { children: React.ReactNode }) {
  const field = useFieldContext('FieldDescription');
  return <p id={field.descriptionId}>{children}</p>;
}

export function FieldError({ children }: { children?: React.ReactNode }) {
  const field = useFieldContext('FieldError');

  if (!field.invalid && !children) return null;

  return (
    <p id={field.errorId} role="alert">
      {children}
    </p>
  );
}

Form library state:
  value, touched, dirty, validation lifecycle, submission lifecycle

Design system field context:
  id, label linkage, invalid flag, required flag, disabled flag, described-by ids

function CaseFormTextField({ name, label }: { name: string; label: string }) {
  const field = useController({ name });
  const error = field.fieldState.error?.message;

  return (
    <Field name={name} error={error} required>
      <Label>{label}</Label>
      <Input
        value={field.field.value ?? ''}
        onChange={field.field.onChange}
        onBlur={field.field.onBlur}
      />
      <FieldError>{error}</FieldError>
    </Field>
  );
}

<Fieldset disabled>
  <TextField name="firstName" />
  <TextField name="lastName" />
</Fieldset>

type FieldsetContextValue = {
  disabled: boolean;
  readOnly: boolean;
};

const FieldsetContext = createContext<FieldsetContextValue>({
  disabled: false,
  readOnly: false,
});

export function Fieldset({
  disabled = false,
  readOnly = false,
  children,
}: {
  disabled?: boolean;
  readOnly?: boolean;
  children: React.ReactNode;
}) {
  const value = useMemo(() => ({ disabled, readOnly }), [disabled, readOnly]);

  return (
    <FieldsetContext value={value}>
      <fieldset disabled={disabled}>{children}</fieldset>
    </FieldsetContext>
  );
}

export function useFieldsetContext() {
  return useContext(FieldsetContext);
}

function TextInput(props: React.InputHTMLAttributes<HTMLInputElement>) {
  const fieldset = useFieldsetContext();

  return (
    <input
      {...props}
      disabled={props.disabled ?? fieldset.disabled}
      readOnly={props.readOnly ?? fieldset.readOnly}
    />
  );
}

Local prop override group context?
Group context override local prop?
Apakah disabled bisa di-enable lagi di child?
Apakah readonly berbeda dari disabled?

<Tabs defaultValue="details">
  <Tabs.List>
    <Tabs.Trigger value="details">Details</Tabs.Trigger>
    <Tabs.Trigger value="history">History</Tabs.Trigger>
  </Tabs.List>
  <Tabs.Panel value="details">...</Tabs.Panel>
  <Tabs.Panel value="history">...</Tabs.Panel>
</Tabs>

type TabsContextValue = {
  value: string;
  setValue: (value: string) => void;
  baseId: string;
};

const TabsContext = createContext<TabsContextValue | null>(null);

function useTabsContext(component: string) {
  const value = useContext(TabsContext);
  if (!value) throw new Error(`${component} must be used inside <Tabs>`);
  return value;
}

export function Tabs({
  value: controlledValue,
  defaultValue,
  onValueChange,
  children,
}: {
  value?: string;
  defaultValue?: string;
  onValueChange?: (value: string) => void;
  children: React.ReactNode;
}) {
  const baseId = useId();
  const [uncontrolledValue, setUncontrolledValue] = useState(defaultValue ?? '');

  const isControlled = controlledValue !== undefined;
  const value = isControlled ? controlledValue : uncontrolledValue;

  const setValue = useCallback(
    (nextValue: string) => {
      if (!isControlled) setUncontrolledValue(nextValue);
      onValueChange?.(nextValue);
    },
    [isControlled, onValueChange]
  );

  const contextValue = useMemo(
    () => ({ value, setValue, baseId }),
    [value, setValue, baseId]
  );

  return <TabsContext value={contextValue}>{children}</TabsContext>;
}

export function TabsTrigger({
  value,
  children,
}: {
  value: string;
  children: React.ReactNode;
}) {
  const tabs = useTabsContext('TabsTrigger');
  const selected = tabs.value === value;
  const triggerId = `${tabs.baseId}-trigger-${value}`;
  const panelId = `${tabs.baseId}-panel-${value}`;

  return (
    <button
      id={triggerId}
      role="tab"
      type="button"
      aria-selected={selected}
      aria-controls={panelId}
      tabIndex={selected ? 0 : -1}
      onClick={() => tabs.setValue(value)}
    >
      {children}
    </button>
  );
}

export function TabsPanel({
  value,
  children,
}: {
  value: string;
  children: React.ReactNode;
}) {
  const tabs = useTabsContext('TabsPanel');
  const selected = tabs.value === value;
  const triggerId = `${tabs.baseId}-trigger-${value}`;
  const panelId = `${tabs.baseId}-panel-${value}`;

  return (
    <div
      id={panelId}
      role="tabpanel"
      aria-labelledby={triggerId}
      hidden={!selected}
    >
      {selected ? children : null}
    </div>
  );
}

Context coordinates data.
ARIA defines semantics.
Keyboard logic defines interaction.
Focus management defines usability.

<button
  data-state={selected ? 'active' : 'inactive'}
  data-disabled={disabled ? '' : undefined}
  data-density={density}
/>

.ds-tabs-trigger[data-state="active"] {
  border-block-end-color: var(--ds-color-accent);
}

.ds-button[data-density="compact"] {
  min-height: 32px;
}

// Bad smell
<div data-current-invoice-status="under-investigation" />

Token visual stabil      -> CSS variables
Mode/current selection   -> Context or DOM attribute
Behavioral decision      -> Context
Huge token dictionary    -> Avoid in context

const token = useContext(TokenContext);
return <div style={{ color: token.colors.text.default }} />;

return <div className="ds-card" />;

.ds-card {
  color: var(--ds-color-text-default);
  background: var(--ds-color-surface-default);
  border-radius: var(--ds-radius-md);
}

<ColorSchemeProvider scheme={customerBrandScheme}>
  <PartnerPortal />
</ColorSchemeProvider>

<Card>
  <Card.Header />
  <Card.Body />
  <Card.Footer />
</Card>

type CardContextValue = {
  variant: 'plain' | 'outlined' | 'elevated';
  density: 'comfortable' | 'compact';
};

const CardContext = createContext<CardContextValue | null>(null);

function Card({
  variant = 'plain',
  density = 'comfortable',
  children,
}: {
  variant?: CardContextValue['variant'];
  density?: CardContextValue['density'];
  children: React.ReactNode;
}) {
  const value = useMemo(() => ({ variant, density }), [variant, density]);

  return (
    <CardContext value={value}>
      <section data-variant={variant} data-density={density} className="ds-card">
        {children}
      </section>
    </CardContext>
  );
}

function CardHeader({ children }: { children: React.ReactNode }) {
  const card = useContext(CardContext);

  return (
    <header
      className="ds-card-header"
      data-card-variant={card?.variant}
      data-density={card?.density}
    >
      {children}
    </header>
  );
}

.ds-card[data-density="compact"] .ds-card-header {
  padding: 8px;
}

Jika child hanya perlu styling dari parent, CSS sering lebih murah dari Context.
Jika child perlu behavior/ARIA/id/registration, Context lebih masuk akal.

type ItemRecord = {
  id: string;
  ref: React.RefObject<HTMLElement | null>;
  disabled: boolean;
};

type RovingFocusContextValue = {
  registerItem: (item: ItemRecord) => () => void;
  moveNext: () => void;
  movePrevious: () => void;
  activeId: string | null;
};

function RovingFocusProvider({ children }: { children: React.ReactNode }) {
  const itemsRef = useRef<Map<string, ItemRecord>>(new Map());
  const [activeId, setActiveId] = useState<string | null>(null);

  const registerItem = useCallback((item: ItemRecord) => {
    itemsRef.current.set(item.id, item);

    return () => {
      itemsRef.current.delete(item.id);
    };
  }, []);

  const moveNext = useCallback(() => {
    const items = Array.from(itemsRef.current.values()).filter(item => !item.disabled);
    if (items.length === 0) return;

    const currentIndex = items.findIndex(item => item.id === activeId);
    const next = items[(currentIndex + 1) % items.length];
    setActiveId(next.id);
    next.ref.current?.focus();
  }, [activeId]);

  const movePrevious = useCallback(() => {
    const items = Array.from(itemsRef.current.values()).filter(item => !item.disabled);
    if (items.length === 0) return;

    const currentIndex = items.findIndex(item => item.id === activeId);
    const previous = items[(currentIndex - 1 + items.length) % items.length];
    setActiveId(previous.id);
    previous.ref.current?.focus();
  }, [activeId]);

  const value = useMemo(
    () => ({ registerItem, moveNext, movePrevious, activeId }),
    [registerItem, moveNext, movePrevious, activeId]
  );

  return <RovingFocusContext value={value}>{children}</RovingFocusContext>;
}

portal host
+ stacking order
+ escape key
+ outside click
+ focus return
+ inert background
+ scroll lock
+ nested overlay
+ dismissal policy

type LayerManager = {
  registerLayer: (layer: LayerRecord) => () => void;
  isTopLayer: (id: string) => boolean;
  dismissTopLayer: () => void;
};

function Dialog({ open, onOpenChange, children }: DialogProps) {
  const layerManager = useLayerManager();
  const id = useId();

  useEffect(() => {
    if (!open) return;

    return layerManager.registerLayer({
      id,
      type: 'dialog',
      dismiss: () => onOpenChange(false),
    });
  }, [open, id, layerManager, onOpenChange]);

  if (!open) return null;

  return createPortal(
    <div role="dialog" aria-modal="true">
      {children}
    </div>,
    document.body
  );
}

Design system component:
  Button, TextField, Dialog, Tabs, Menu, DataTable primitive

Product component:
  CaseStatusBadge, EnforcementActionPanel, InvoiceApprovalTimeline

// Bad smell
function Button(props: ButtonProps) {
  const permission = usePermission();
  const caseStatus = useCaseStatus();

  return <button disabled={!permission.canEditCase || caseStatus === 'closed'} />;
}

function Button(props: ButtonProps) {
  return <button {...props} />;
}

function EditCaseButton({ caseId }: { caseId: string }) {
  const permission = useCasePermission(caseId);

  return (
    <Button disabled={!permission.canEdit}>
      Edit case
    </Button>
  );
}

<Button disabled tooltip="You do not have permission to edit this case">
  Edit
</Button>

<DesignSystemProvider>
  <PublicPortalTheme>
    <PublicRoutes />
  </PublicPortalTheme>

  <WorkspaceTheme density="compact">
    <InternalRoutes />
  </WorkspaceTheme>
</DesignSystemProvider>

Provider terdekat menang.
Nested provider tidak boleh membuat state parent corrupt.
Override harus documented.

function Surface({ tone = 'default', children }: SurfaceProps) {
  return (
    <SurfaceToneContext value={tone}>
      <section data-surface-tone={tone}>{children}</section>
    </SurfaceToneContext>
  );
}

function Divider() {
  const tone = useContext(SurfaceToneContext);
  return <hr data-surface-tone={tone} />;
}

Style belongs to CSS when possible.
Behavior coordination belongs to React.
Cross-cutting scoped capability belongs to Context.

cost = update frequency × consumer fan-out × render weight × interaction sensitivity

<GridContext value={{ hoveredRowId, selectedRows, columns, rows, sort, filter }}>
  {children}
</GridContext>

1. Apakah value ini benar-benar ambient untuk subtree?
2. Apakah value ini domain-agnostic?
3. Apakah scope provider sudah sekecil mungkin?
4. Apakah update frequency rendah?
5. Apakah styling bisa diselesaikan via CSS variables/data attributes?
6. Apakah context membawa object besar?
7. Apakah ada default value yang bisa menutupi missing provider bug?
8. Apakah consumer punya custom hook dengan error message jelas?
9. Apakah context mempermudah accessibility contract?
10. Apakah context bisa di-override di test/storybook?
11. Apakah provider menyebabkan remount tidak sengaja?
12. Apakah ada migration path jika context menjadi bottleneck?

it('connects label, input, description, and error', () => {
  render(
    <Field error="Required" required>
      <Label>Email</Label>
      <Input />
      <FieldDescription>Use your work email.</FieldDescription>
      <FieldError>Required</FieldError>
    </Field>
  );

  const input = screen.getByLabelText(/email/i);

  expect(input).toHaveAttribute('aria-invalid', 'true');
  expect(input).toHaveAccessibleDescription(/use your work email/i);
  expect(screen.getByRole('alert')).toHaveTextContent('Required');
});

it('reverses horizontal intent in RTL mode', async () => {
  render(
    <DirectionProvider dir="rtl">
      <Tabs defaultValue="one">
        <Tabs.List>
          <Tabs.Trigger value="one">One</Tabs.Trigger>
          <Tabs.Trigger value="two">Two</Tabs.Trigger>
        </Tabs.List>
      </Tabs>
    </DirectionProvider>
  );

  await user.keyboard('{ArrowLeft}');

  expect(screen.getByRole('tab', { name: /two/i })).toHaveAttribute('aria-selected', 'true');
});

it('uses nearest density provider', () => {
  render(
    <DensityProvider value="comfortable">
      <Button>Comfortable</Button>
      <DensityProvider value="compact">
        <Button>Compact</Button>
      </DensityProvider>
    </DensityProvider>
  );

  expect(screen.getByRole('button', { name: /comfortable/i })).toHaveAttribute(
    'data-density',
    'comfortable'
  );

  expect(screen.getByRole('button', { name: /compact/i })).toHaveAttribute(
    'data-density',
    'compact'
  );
});

export const decorators = [
  (Story, context) => (
    <ThemeProvider initialMode={context.globals.theme}>
      <DensityProvider value={context.globals.density}>
        <DirectionProvider dir={context.globals.dir}>
          <Story />
        </DirectionProvider>
      </DensityProvider>
    </ThemeProvider>
  ),
];

light/dark
comfortable/compact
ltr/rtl
valid/invalid
enabled/disabled/readOnly
controlled/uncontrolled
keyboard/mouse/touch

type BadThemeContextValue = {
  theme: Theme;
  setTheme: (theme: Theme) => void;
  spacing: Record<string, number>;
  colors: Record<string, string>;
  typography: Record<string, unknown>;
  currentUserBrand: Brand;
  permissions: PermissionMap;
  featureFlags: FeatureFlagMap;
  isSidebarOpen: boolean;
  setSidebarOpen: (open: boolean) => void;
};

ThemeProvider        -> mode/resolved mode + CSS variable boundary
DensityProvider      -> density only
PermissionProvider   -> product/application layer, bukan design system primitive
FeatureFlagProvider  -> capability/config layer
SidebarProvider      -> layout boundary

<FieldContext value={{ value, setValue, error, touched, dirty, id }}>

Design system FieldContext:
  id, describedBy, invalid, disabled, required

Form adapter:
  value, onChange, onBlur, error, touched, dirty

function Text({ children }: { children: React.ReactNode }) {
  const theme = useTheme();
  const density = useDensity();

  return (
    <span style={{
      color: theme.colors.text,
      fontSize: density === 'compact' ? 12 : 14,
    }}>
      {children}
    </span>
  );
}

function Text({ children }: { children: React.ReactNode }) {
  return <span className="ds-text">{children}</span>;
}

.ds-text {
  color: var(--ds-color-text-default);
  font-size: var(--ds-font-size-body);
}

<div data-theme={resolvedTheme} data-density={density}>{children}</div>

Symptom:
  Semua aplikasi rerender saat satu panel berubah.

Fix:
  Turunkan provider ke feature boundary.

Symptom:
  Theme switch membuat semua component rerender berat.

Fix:
  Pindahkan token visual ke CSS variables.

Symptom:
  Button tidak bisa dipakai di luar app tertentu.

Fix:
  Pindahkan domain decision ke product component.

Symptom:
  Design system sulit diganti form library.

Fix:
  Pisahkan field accessibility context dari form state adapter.

Symptom:
  Parts saling bergantung secara tidak jelas.

Fix:
  Batasi scope, enforce provider, expose public API eksplisit.

Symptom:
  Consumer rerender walau value logis tidak berubah.

Fix:
  Memoize value atau split context.

Symptom:
  Component behave salah di test/storybook tanpa error.

Fix:
  Gunakan strict context untuk context yang wajib.

[ ] Context name spesifik, bukan AppContext/UIContext generic.
[ ] Value kecil dan jelas.
[ ] Scope provider minimal.
[ ] Styling utama memakai CSS variables/data attributes jika memungkinkan.
[ ] Context tidak membawa domain data.
[ ] Context tidak membawa high-frequency state besar.
[ ] Custom hook memberi error jelas saat provider hilang.
[ ] Provider value identity stabil.
[ ] Ada override story/test harness.
[ ] Accessibility contract dites.
[ ] RTL/density/theme variations dites.
[ ] Ada documented merge rule antara props lokal dan group context.
[ ] Ada migration path jika context menjadi bottleneck.

Use Context for:
  ambient UI environment,
  compound component coordination,
  accessibility linkage,
  scoped capabilities.

Avoid Context for:
  token dictionary besar,
  high-frequency UI state,
  domain data,
  form value engine tersembunyi,
  styling yang bisa diselesaikan CSS.