{"title":"POS styling API","slug":"pos-styling-api","url":"https://support.storeconnect.com/articles/pos-styling-api","url_markdown":"https://support.storeconnect.com/articles/pos-styling-api.md","subtitle":null,"summary":"The rules for restyling the POS with CSS that keeps working across releases: the published parts, attributes, component properties, and design tokens, how to select them, which components have them, what to do when an element has none, and how names are added and retired. Read it with a component styling reference such as Button.","type":"Developer_Documentation","video_url":"","keywords":"pos styling api, parts, part attribute, component properties, custom properties, design tokens, data-variant, data-tone, data-size, pos css, style block, cascade layers, retired parts, pos upgrade css","last_modified":"2026-11-17T05:18:36+0000","body_markdown":"Use this reference when you write CSS for the point of sale that has to keep working after\nan upgrade. The CSS goes in a [style block with `POS` in **Channels**](style-the-pos#create-a-style-block-for-the-pos)\nor in a `\u003cstyle\u003e` element in a [POS view](pos-views#css-in-a-view). Your styles keep working\nwhen the POS is upgraded as long as they use only these four kinds of name:\n\n1.  **Component properties**: settings a component reads, such as `--sc-button-bg` for a\n    button's fill. Use these first.\n2.  **Parts**: named pieces of a component, such as a button's label, selected with\n    `[part~='button-label']`. Use a part when no property does the job. Some elements on a\n    screen also have a name of their own, such as the cart's Pay button. The component's\n    reference article lists them.\n3.  **Attributes**: which kind of a component it is, such as `data-variant` on a button, or\n    what state one of its parts is in, such as `aria-current` on the row of a record table\n    that is open, so you can style one kind or one state only. The component's reference\n    article lists each one with the values it takes, and the part it is on when that is not\n    the component's root.\n4.  **Design tokens**: the colors, fonts, and type scales every component is styled from,\n    such as `--sc-color-primary`. Set one on `:root` to change the whole POS at once. The\n    [POS design tokens reference](pos-design-tokens-reference) lists them.\n\nTogether these are the POS styling API. Everything else is internal and can change in any\nrelease: class names, IDs, `data-*` and ARIA attributes the component's article does not\nlist, element types, and the structure of the markup. A part stays on an element that does\nthe same job. Where the element sits and the markup around it can change.\n\nYou do not need `!important`. Every published component loads its styles in cascade layers,\nso a rule in your style block or view wins over them at any specificity. The exceptions are\nlisted under \"What can't be styled yet\" on each component's article. The rest of the POS's\nstyles, including layout classes a screen adds to a component, are outside the layers and\nfollow normal specificity, which is one reason to leave layout alone.\n\n## Published components\n\n| Component | What it covers | Available from | Reference |\n| --- | --- | --- | --- |\n| Button | Standalone buttons, such as the Pay button in the cart, the buttons on the payment screens, and the buttons in most dialogs | v22.0.4 | [Button styling reference](pos-button-styling-reference) |\n| Card | The tiles screens lay out, such as products in a products grid, the tiles of an action grid, and a bundle's components | v22.0.10 | [Card styling reference](pos-card-styling-reference) |\n| Layout | How screens arrange cards and tiles, such as the products grid, the lists of records, and action grids | v22.0.8 | [Layout styling reference](pos-layout-styling-reference) |\n| List button | The items of the navigation and of menus: each action item in the sidebar and the bar, the More button, the button that collapses the sidebar, the cart button on the bar, and the items a group opens | v22.0.14 | [List button styling reference](pos-list-button-styling-reference) |\n| Loading dots | The three pulsing dots beside a status that is still changing, such as the preparing state on an open order's line | v22.0.14 | [Loading dots styling reference](pos-loading-dots-styling-reference) |\n| Media image | The images on product cards and action tiles, the thumbnails on cart rows and order items, the pictures in list items and the variants menu, and the gallery on a product's screen | v22.0.13 | [Media image styling reference](pos-media-image-styling-reference) |\n| Menu | The menus the action navigation opens, such as a group's items floating from the sidebar or the bar, and a group opened inside the More menu | v22.0.13 | [Menu styling reference](pos-menu-styling-reference) |\n| Product price | The prices on product cards, in product lists and on variants, at the top of a product's screen and a bundle's screen, and on a bundle's components | v22.0.7 | [Product price styling reference](pos-product-price-styling-reference) |\n| Record table | The tables of records in a list, such as the customers and orders lists, and the results of a quick search | v22.0.7 | [Record table styling reference](pos-record-table-styling-reference) |\n\nThe **Available from** column shows the first release that carries the names.\n\nEvery other component has no parts or properties yet. CSS that reaches one has to select\nthe app's own classes, which are internal and can change in any release. See\n[If what you need has no part yet](#if-what-you-need-has-no-part-yet).\n\n## Design tokens\n\nThe [POS design tokens reference](pos-design-tokens-reference) lists the values every\ncomponent is styled from, grouped by what they are for, with examples. The tokens are part of\nthe styling API from TBD. The names themselves go back further: each table in the reference\nshows the release that first carried the token.\n\n## Rules\n\n1.  Use only the parts, attributes, and component properties listed on the component's\n    reference article, and the tokens listed on the\n    [POS design tokens reference](pos-design-tokens-reference).\n2.  Select a part with `[part~='name']`\n    ([how attribute selectors work](https://developer.mozilla.org/en-US/docs/Web/CSS/Attribute_selectors)).\n    Always `~=`, never `=` or `^=`: an element can carry more than one part, and `~=` still\n    matches it.\n3.  To style a part inside one component, write the component's root part or name, a space,\n    then the part: `[part~='cart-checkout-button'] [part~='button-label']`. The part after\n    the space must belong to that component, as the reference article lists it. Nothing else\n    goes around a part: no `\u003e`, `+`, or `~`, no structural pseudo-classes such as\n    `:first-child`, `:nth-child()`, `:empty`, or `:has()`, and never more than two parts.\n4.  To style one kind of a component, narrow the root part by an attribute the reference\n    article lists, inside `:where()`: `[part~='button-root']:where([data-variant='filled'])`.\n    One attribute per `:where()`; for two kinds at once, write two:\n    `:where([data-variant='filled']):where([data-tone='primary'])`. Inside `:where()` the\n    attribute does not make the rule stronger, so it ties with a rule for one named element,\n    and the later rule wins. Write the rule for a named element after the rules for the kind.\n    An attribute the reference article lists on another part, such as\n    `record-table-row[aria-current]`, narrows that part the same way:\n    `[part~='record-table-row']:where([aria-current='true'])`.\n5.  A part may end with a state pseudo-class (`:hover`, `:focus-visible`, `:active`,\n    `:disabled`) or a pseudo-element (`::before`, `::after`).\n6.  Do not select classes, IDs, element types, or attributes other than the listed ones.\n    They are internal: selecting them works today, but it can break in any release.\n7.  Prefer a component property to a plain CSS property when one does the job. The component\n    handles the rest, including how it looks when hovered or pressed. A component's\n    properties cover what it draws inside itself too, such as `--sc-button-icon-size` for a\n    button's icons. Set a property on the root part to change every instance, on the root\n    part narrowed by an attribute to change one kind, or on a named part to change one\n    instance. A property set on `:root` reaches every component, unless something closer to\n    the component sets it. To change every component at once, set a\n    [design token](pos-design-tokens-reference) on `:root` instead.\n8.  A property applies to every kind of the component unless the rule narrows it away.\n    Every kind of button reads `--sc-button-bg`, so setting it for `data-tone='primary'`\n    alone gives primary text buttons a fill too. Narrow by each attribute that matters. Size\n    is a kind too: `--sc-button-icon-size` on the root part replaces the icon size of every\n    button size, so narrow by `data-size` to change one. A property set after a state, such\n    as `:where([data-variant='filled']):active`, applies in that state only.\n9.  Change appearance only: color, background, border, radius, font, and inner padding.\n    Leave `display`, `position`, `order`, `width`, and outer margin alone, because they\n    depend on the screen around the component.\n10. Your styles win over a published component's own styles without `!important`, except\n    where the component's reference article lists them under \"What can't be styled yet\".\n11. Parts are for CSS only. Never select them from a script. Scripts use the\n    [POS actions](pos-actions-reference) through [scAction](pos-sc-action).\n\n## If what you need has no part yet\n\n1.  Check whether a [design token](pos-design-tokens-reference) or the **Color** field on a\n    **POS Action Item** does the job. Tokens reach every screen, and **Color** reaches one\n    action button.\n2.  Raise a [support case](manage-your-support-cases) that names the screen and the element,\n    and asks for a part or property. Parts are added to components as stores ask for them.\n3.  If you go ahead with CSS that selects the app's own classes, keep it in a style block of\n    its own, note which screens it touches, and check those screens after every upgrade. It\n    can stop working or style something else in any release.\n\n## When parts change\n\n-   New parts, attributes, properties, and tokens can arrive in any release. Each\n    component's article, and the design tokens reference, shows the release each one first\n    shipped in.\n-   The markup around a part can change in any release, but the part stays on an element\n    that does the same job.\n-   A part, property, attribute value, or token is only removed, renamed, or changed to mean\n    something else in a major release. A release retires it first: the release notes say\n    so, and the component's article, or the design tokens reference, lists it under\n    \"Retired\", with what replaces it and the major release that removes it. It keeps working\n    until that release, so you have until then to move your styles off it.\n-   The POS's own look, such as the default colors and spacing, can change in any release.\n    Your styles still apply, but the result can look different.\n\n## AI tools\n\nIf you use an AI tool to write your styles, give it this article and the articles for the\ncomponents you want to change. To change the whole POS, also give it the\n[POS design tokens reference](pos-design-tokens-reference). Ask the tool to use only the parts,\nattributes, properties, and tokens listed in those articles, and to tell you when a request\nneeds anything else. Without these articles,\nthe tool inspects the POS and uses whatever class names it finds, and those can change in\nany release. See [Build POS with an AI agent](pos-with-ai-agents) for setting an agent up.\n\n## Component markup copied into a view\n\nA view can copy a component's markup, classes, and attributes to draw something that looks\nlike it. That works, but it is not kept working between releases: the copied classes and\nstructure can change in any release, and the copy has no parts unless it writes them itself."}