Carbon v11 style integration (component checklist)

[theetrain]

trafficstars

📣 Status: implementing. Contributions are welcome! See https://github.com/carbon-design-system/carbon-components-svelte/discussions/1872 for details and contribution guide.

This is a placeholder ticket to track the integration of Carbon v11 styles into carbon-components-svelte. Adopting Carbon v11 styles is our highest priority, but shipping components with <style lang="sass"> is currently problematic with Vite as discussed in #1561.

Prior research

I'm currently evaluating @sveltejs/package in the carbon-v11 branch in order to accomodate these aspirational goals:

• [x] ✅ Write components using <script lang="ts"> to distribute as JS Svelte components and companion *.svelte.d.ts files for TypeScript users. See guide on adding types to components (works well!)
• [x] ✅ Ensure Sveld can interpret typings to generate documentation (yes, but needs enhancements to read in types from svelte/elements)
• [x] ✅ Import Carbon v11 SCSS directly via <style lang="sass">@use ...</style> and rely on @sveltejs/package to compile styles into scoped CSS (yes, SCSS builds as scoped CSS)
• [x] ✅ Ensure there's a way to theme components via CSS variables once SCSS compiles to scoped CSS in each component (yes, compiled SCSS ships with CSS variables and default values)
• [x] ✅ Test build performance on a plain SvelteKit app (it's good because components are precompiled)

If the above goals turn out to be favourable, we'll proceed to implement Carbon v11 styles into every component. Special thanks to @gregorw for early exploration in #1496.

Later, or out of scope:

• [ ] Provide general documentation for CSS variables for feature overrides
• [x] Add <Stack /> (#1384) to provide custom spacing or sectioning
• [ ] Split work into per-component tasks, tracked in this ticket. Open up for contributions

Checklist

• [x] Accordion
• [x] AccordionItem
• [x] AccordionSkeleton
• [x] AspectRatio
• [x] Breadcrumb
• [x] BreadcrumbItem
• [x] BreadcrumbSkeleton
• [x] Breakpoint
• [ ] https://github.com/carbon-design-system/carbon-components-svelte/issues/1641
• [x] ButtonSet
• [x] ButtonSkeleton
• [ ] Checkbox
• [ ] CheckboxSkeleton
• [ ] ClickableTile
• [ ] CodeSnippet
• [ ] CodeSnippetSkeleton
• [x] Column
• [ ] https://github.com/carbon-design-system/carbon-components-svelte/issues/1679
• [ ] ComposedModal
• [ ] Content
• [ ] ContentSwitcher
• [ ] ContextMenu
• [ ] ContextMenuDivider
• [ ] ContextMenuGroup
• [ ] ContextMenuOption
• [ ] ContextMenuRadioGroup
• [ ] CopyButton
• [ ] DataTable
• [ ] DataTableSkeleton
• [ ] DatePicker
• [ ] DatePickerInput
• [ ] DatePickerSkeleton
• [ ] Dropdown
• [ ] DropdownSkeleton
• [ ] ExpandableTile
• [ ] FileUploader
• [ ] FileUploaderButton
• [ ] FileUploaderDropContainer
• [ ] FileUploaderItem
• [ ] FileUploaderSkeleton
• [ ] Filename
• [ ] FluidForm
• [ ] Form
• [ ] FormGroup
• [ ] FormItem
• [ ] FormLabel
• [x] Grid
• [ ] Header
• [ ] HeaderAction
• [ ] HeaderActionLink
• [ ] HeaderGlobalAction
• [ ] HeaderNav
• [ ] HeaderNavItem
• [ ] HeaderNavMenu
• [ ] HeaderPanelDivider
• [ ] HeaderPanelLink
• [ ] HeaderPanelLinks
• [ ] HeaderSearch
• [ ] HeaderUtilities
• [ ] ImageLoader
• [x] InlineLoading
• [ ] InlineNotification
• [x] #1892
• [ ] Link
• [ ] ListBox
• [ ] ListBoxField
• [ ] ListBoxMenu
• [ ] ListBoxMenuIcon
• [ ] ListBoxMenuItem
• [ ] ListBoxSelection
• [x] ListItem
• [x] Loading
• [ ] LocalStorage
• [ ] Modal
• [ ] ModalBody
• [ ] ModalFooter
• [ ] ModalHeader
• [ ] MultiSelect
• [ ] NotificationActionButton
• [ ] NotificationButton
• [ ] NotificationIcon
• [ ] NumberInput
• [ ] NumberInputSkeleton
• [x] OrderedList
• [ ] OutboundLink
• [ ] OverflowMenu
• [ ] OverflowMenuItem
• [ ] Pagination
• [ ] PaginationNav
• [ ] PaginationSkeleton
• [ ] #1890
• [ ] #1896
• [ ] ProgressBar
• [ ] ProgressIndicator
• [ ] ProgressIndicatorSkeleton
• [ ] ProgressStep
• [ ] RadioButton
• [ ] RadioButtonGroup
• [ ] RadioButtonSkeleton
• [ ] RadioTile
• [x] RecursiveList
• [x] Row
• [x] Search
• [x] SearchSkeleton
• [ ] https://github.com/carbon-design-system/carbon-components-svelte/issues/1675
• [ ] SelectItem
• [ ] SelectItemGroup
• [ ] SelectSkeleton
• [ ] SelectableTile
• [ ] SideNav
• [ ] SideNavDivider
• [ ] SideNavItems
• [ ] SideNavLink
• [ ] SideNavMenu
• [ ] SideNavMenuItem
• [ ] SkeletonPlaceholder
• [ ] SkeletonText
• [ ] SkipToContent
• [ ] Slider
• [ ] SliderSkeleton
• [x] StructuredList
• [x] StructuredListBody
• [x] StructuredListCell
• [x] StructuredListHead
• [x] StructuredListInput
• [x] StructuredListRow
• [x] StructuredListSkeleton
• [ ] Switch
• [ ] Tab
• [ ] TabContent
• [ ] Table
• [ ] TableBody
• [ ] TableCell
• [ ] TableContainer
• [ ] TableHead
• [ ] TableHeader
• [ ] TableRow
• [ ] Tabs
• [ ] TabsSkeleton
• [ ] Tag
• [ ] TagSkeleton
• [x] https://github.com/carbon-design-system/carbon-components-svelte/issues/1668
• [x] TextAreaSkeleton
• [x] https://github.com/carbon-design-system/carbon-components-svelte/issues/1661
• [x] #1888
• [ ] TextInputSkeleton
• [ ] https://github.com/carbon-design-system/carbon-components-svelte/issues/1653
• [ ] Tile
• [ ] TileGroup
• [ ] TimePicker
• [ ] TimePickerSelect
• [ ] ToastNotification
• [ ] Toggle
• [ ] ToggleSkeleton
• [ ] Toolbar
• [ ] ToolbarBatchActions
• [ ] ToolbarContent
• [ ] ToolbarMenu
• [ ] ToolbarMenuItem
• [ ] ToolbarSearch
• [ ] Tooltip
• [ ] TooltipDefinition
• [ ] TooltipFooter
• [ ] TooltipIcon
• [ ] TreeView
• [x] Truncate
• [x] UnorderedList
• [ ] https://github.com/carbon-design-system/carbon-components-svelte/issues/1674
• [ ] Change CSS prefix from bx to cds to match flagship

---

New components

• [ ] Grid (uses CSS Grid)
• [ ] FlexGrid (old grid)
• [ ] ContainedList
• [x] Section
• [x] Heading (designed to pair with section)
• [ ] MenuButton (mix of Button and OverflowMenu)
• [ ] ComboButton (similar to menu button, but the button has a dedicated action instead of just opening the dropdown)
• [x] Stack
• [ ] Tag (more variants)
• [ ] Icon (for setting size)
• [ ] SkeletonIcon

[theetrain]

@metonym some good progress so far (see notes above).

Here's a TypeScript follow up to https://github.com/carbon-design-system/carbon-components-svelte/pull/1628#issuecomment-1383310189

import type { HTMLLabelAttributes } from "svelte/elements";

export let labelAttributes: HTMLLabelAttributes = {};

This will produce HTML types for the respective element. This will probably improve DX when adding props to components because you'll see the Carbon props as well as labelAttributes instead of carbon props mixed with every possible HTML attribute in alphabetical order. I updated #1621 with the proposed name convention.

We can add lang="ts" gradually as we refactor components since JSDoc compiles fine as is. One thing I'd like to change is place import statements before export statements to follow ESM conventions.

Try this locally:

• checkout the feat/carbon-v11 branch
• run yarn then yarn build:package
• Observe output in package/TextInput/TextInput.svelte.d.ts
• Observe built css in package/Button/Button.svelte

Once I'm finished evaluating and setting up the new project structure with svelte-package, I think we can keep feat/carbon-v11 as a long-running branch and adopt v11 styles one at a time, making pull requests targeting feat/carbon-v11. I can add a task list above to see who's working on which components.

Let me know if you have any feedback.

[metonym]

@theetrain proof-of-concept LGTM

[theetrain]

We made the first prerelease: v1.0.0-next.0

Updated the ticket body above, as well as the related discussion. For those following, see the contribution guide: https://github.com/carbon-design-system/carbon-components-svelte/discussions/1872

[SimpleProgrammingAU]

I've been playing around today getting used to how to contribute for this. I have been working on TextInput if you'd like me to take care of that one. I can probably post a PR for that one tomorrow. Be a good first test to make sure I know what I'm doing. I can also have a look through the open bugs and address those in my changes, too.

[SimpleProgrammingAU]

@theetrain if you have the time and energy to setup a few more issues for v11 components that are unlikely to have dependencies on other components, I've got a bit of time and motivation at the moment to hammer some out (so long as you're okay with a pile of PRs sitting in the queue haha).

[metonym]

New Components

• [ ] Grid (uses CSS Grid)
• [ ] FlexGrid (old grid)
• [ ] ContainedList
• [ ] Heading
• [ ] MenuButton (mix of Button and OverflowMenu)
• [ ] ComboButton (similar to menu button, but the button has a dedicated action instead of just opening the dropdown)
• [ ] Stack
• [ ] Tag (more variants)
• [ ] Icon (for setting size)

[metonym]

I've deployed this branch as a static site preview here: https://next-carbon-components-svelte.onrender.com/

I'm using it to visually compare between the master branch for any styling regressions.

[brunnerh]

Regarding new components, there is Tooltip/Toggletip; the pre-v11 Tooltip sort of becomes Toggletip as that one has to be manually toggled and is allowed to contain interactive elements.