Semantic & Foundation Tokens

ApollionProvider exposes two public token layers — each with a clear role and a different audience.

Foundation is what product consumes day to day. Semantic is the internal layer @apollion-dsi/core components use to dress themselves. You rarely touch Semantic, except when composing a new component in the DS's own pattern.

Foundation — recommended for product

import { Flex } from '@apollion-dsi/core/containers/flex';
import { Text } from '@apollion-dsi/core/elements/text';
 
<Flex bgColor="primary" p="large">
  <Text color="primary" fontWeight="bold">
    Content
  </Text>
</Flex>;

Foundation aliases are resolved against the current theme — switching ApollionProvider from light to dark (or from one brand to another) re-resolves without rewriting the component.

Live demo

The same Foundation alias (primary) renders differently depending on the current theme. There's no if (isDark) in consumer code — the component stays a single one.

Semantic — used by DS components

@apollion-dsi/core components consume theme.semantic.<intent> internally. You rarely touch this layer — unless you're composing a new component in the DS's own pattern.

const StyledButton = styled.button`
  background: ${({ theme, $intent }) => theme.semantic[$intent].background};
  color: ${({ theme, $intent }) => theme.semantic[$intent].text};
`;

Best practices

1. Default: Foundation. Anyone designing product screens stays in this layer.
2. New component in the DS pattern: Semantic, mirroring the pattern of core's own components.
3. One-off override: prefer creating a new Foundation alias before pointing at a literal palette value.

See also

• Surface Inversion — surface="negative" on containers.
• Dimensions — compact / normal / spacious density.
• Create Theme — defining a custom theme.
• @apollion-dsi/tokens — static CSS / JSON / TS build.