# Theme design principles

ASUI separates component behavior from visual styling through semantic theme slots. All styled component families use the shared resolution boundary. See [Applying an ASUI theme](./theme-provider.md) for setup, the [project theme contract](./phase2-contract.md) for composition, and the [theme property reference](./theme-reference.md) for supported properties.

## Principles

- Theme semantic roles, such as background, foreground, border, focus, and disabled appearance.
- Accept complete CSS background and shadow values so themes can choose flat colors or gradients.
- Keep the expressive yellow/classic preset and the simpler neutral preset equally supported.
- Keep project branding, fonts, application layout, and data colors in the consumer.
- Use shared tokens for derived defaults and component overrides for deliberate exceptions.
- Preserve explicit visual prop precedence and complete-theme compatibility.
- Keep `className` and `style` as escape hatches; do not expose every CSS property as a theme slot.

## Text-field example

```tsx
import { createASTheme } from '@eleventheye/asui';

const projectTheme = createASTheme({
  preset: 'neutral',
  components: {
    textfield: {
      containerBackground: '#ffffff',
      inputBackground: '#ffffff',
      inputFocusShadow: 'none',
      focusRing: '2px solid #175cd3',
    },
  },
});
```

Text fields already use semantic backgrounds, borders, icon colors, autofill styling, and size-specific geometry. Do not reintroduce gradient-stop keys into the semantic API. Existing complete themes are adapted centrally rather than read directly by component styles.

## Maintaining the contract

When a real consumer need warrants a new slot, define its scope and precedence, add source JSDoc and preset defaults, and update the component guide and theme reference together. Verify inherited values, local overrides, explicit props, and both presets. Follow the [component development workflow](./component-workflow.md).

The [original project proposal](./project-theming-proposal.md#original-proposal-historical) preserves the migration rationale. Current release and follow-up status belongs in [issue #94](https://github.com/Andrey11/asui/issues/94).