Segmented Control
Segmented Control switches between two to five views of the same content.
Preview
A mutually exclusive switch between views of the same content, applied the moment it is picked. Default size, three segments, icon on. The specimen is live, so pick one.
The published component exposes exactly two properties, Size and Tabs: no text, no icon switch, no way to say which segment is on. Every label reads Option because the label lives on a nested selector instance, and so do Active, Icon and Icon Swap. Building a real control means reaching into each segment one at a time. The count ships as a variant, not a slot.
Tabs
Two to five segments in the same 340 track. The 4px padding never moves, so segments split the remaining 332 evenly; only their width changes. Five is the cap, the same as Tabs.
At Default a segment spends 16 of padding on each side, so five leave 34.4 for the label. Icon is a boolean, and this run has it off. The track is pinned to 340 and fixed on both sides, and each segment fills an equal share of the 332 left over: 166, 110.67, 83 and 66.4 wide. Nothing else differs between the four counts, which is why they ship as a variant rather than as layout.
Size
Two heights, 48 and 38. The segment carries the change: 40 tall at padding 8 and 16 becomes 30 at 6 and 12, label 16/24 to 14/20 at letter spacing .1. Track padding, gap and radius hold.
The track carries neither height directly: 48 and 38 are what you get once a 40 or a 30 segment sits inside 4 of padding. The icon does not move at all, 16 square in both, so at Small it takes a bigger share of a shorter segment. Small is the size to drop the icon on, not the one to keep it.
State
One state, held by exactly one segment. Active takes the bg/white-0 fill, dropShadow/xs and text/strong-950. Inactive carries no fill and drops to text/sub-700. The icon holds fg/soft-500 either way.
The file cannot enforce the one-active rule. Active lives on the nested selector, so a three segment variant carries three independent booleans and nothing stops all three being on at once. That is a rule for your code, not for the component. An unselected segment shows the track straight through, so the label and the pill behind it carry the selection on their own.
Properties
Two variant axes on the published component. The rest sit on the selector inside it, a building block not meant for direct use.
Segmented Control ships 8 variants, 2 sizes across 4 tab counts. The selector ships 4, active across size. The top two rows are the only things an instance can set from the outside; everything below them lives one level down. The count is a variant, the state is not, and the label is neither.
Tokens
Every value the component reads, resolved through its aliases to the primitive underneath.
Radius is dimensions/radius/full on both track and segment. The active fill carries dropShadow/xs: 0 1px 2px at 4 percent over 0 4px 4px at 1 percent. Accordion and Card reach for the same pair, a fair argument for an elevation token. Five colours, no raw primitives. In dark, bg/weak-50 lands on #242427 while the active segment lands on #0E0E0F, so the selected pill is darker than the groove holding it.
Guidelines
Keep the set short and the labels to one word. Segments take an equal share, so the longest label decides the room every other segment gets.
Do not push five long labels through a Default track. Each segment gets 66.4 and spends 32 on padding, so the words clip. Go Small, drop the icon, or use Tabs.
Reach for Tabs when the switch belongs to the content below it, and for this when it belongs to a setting. Both cap at five. Segmented Control is a pill in a groove, iOS-native, applied on pick. Tabs is an underline with no track at all. Same job, opposite chrome, so pick one per screen and do not run both.