List

Usage

• Use List to present a group of related items inside semantic list markup — recommendations, requirements, steps, features, or rankings.
• Compose every list from a List container plus one ListItem per entry.
• Use an ordered list (type="ordered") when position carries meaning — a sequence of steps or a ranking. Never use an ordered list for items with no inherent order.
• Use List for items with no pairing between them. Use DescriptionList instead when each term pairs with a description or definition in a key-value relationship — the two are not interchangeable.
• Hide the marker (styleType="none") when each item leads with an icon that carries the same meaning, such as a checkmark for a completed step. Never leave the default marker visible next to a leading icon.

Types

• Ordered (type="ordered") — renders ol. Use for a series of steps or a ranking where the item's position carries meaning.
• Unordered (type="unordered", the default) — renders ul. Use for items with no inherent order, such as features or requirements.

Appearance

• Gap (gap) — adds space between items. Add gap when items wrap to multiple lines so each item reads as distinct. Leave gap unset for short, single-line items.
• Marker style (styleType) — sets the bullet or number preceding each item, independently of whether the list renders as ol or ul. Accepts disc, circle, square, decimal, decimal-leading-zero, lower-roman, upper-roman, and none.

Behaviors

• Render rich content inside an item — Icon, Link, Strong, and other inline elements can sit alongside plain text within a single ListItem.

Content

• Keep grammatical structure parallel across items. When one item starts with a verb, start every item with a verb.
• Never mix active and passive phrasing across items in the same list.

Implementation Notes

• React: <List> with <ListItem> children; item content is children. Ember: <PlumaList> with <PlumaListItem> in the default block; item content is the default block ({{yield}}).
• type controls the rendered element — "ordered" renders ol, "unordered" (default) renders ul. ListItem always renders li. Use type rather than as to change the element; both components set their element from type and ignore a passed as.
• type="ordered" also sets the marker to decimal. type="unordered" leaves the browser default (disc). Set styleType to override the marker for either type.
• gap takes a space token (the same values as the gap sprinkle) and is applied as top margin on every item after the first. No gap is applied by default — the design doc's "default amount of gap space" describes the built-in list spacing, not a gap value.
• styleType="none" applies an unstyled class that also zeroes the list's left padding and the item's left padding, so hidden-marker lists align flush with surrounding text.
• Passing a styleType value outside the supported set throws at runtime.
• ListItem accepts styleType to override the marker for a single item. styleType="none" on an item is a no-op — hide markers on the List instead.
• Both List and ListItem extend Text and render through it, so they accept every Text prop (text, size, weight, color, family, fontStyle) plus Box layout and sprinkle props. List defaults text to "product-p"; both default color to "inherit".
• Ember invocation takes the @ prefix on all args — <PlumaList @type="ordered" @gap="050">. Arg names, values, and defaults match React.