- Developer Starting Guide
-
Familiarize yourself with the Principles of Solid Design System, which serves as a reference for design guidelines, components, and patterns used in this project. Adhering to these principles will help maintain consistency and a cohesive user experience.
-
Have a look at the demo project to get a better understanding of the design system and its components. You can even install it locally and play around to explore its features and functionalities.
-
Solid Components follows a monorepo structure with packages (e. g.
components) managed bypnpm(which is a replacement fornpm). Linting and Formatting is centralized at root level. Packages have to be run individually (e.g.cd packages/components && pnpm devto start development server). Runpnpm verifyat the root directory periodically, particularly, before pushing changes when a pull request is already opened.
We are creating a library that comprises a lean combination of reusable Web Components and BEM format CSS Classes that adhere to Union design standards. Each have their own technology and purpose:
- Styles (aka style-components): These are standalone CSS files. They don't provide any logic and are often non-interactive.
- Components: These are Web Components. They are often more complex than Styles, and could feature reactivity, state, multiple slots, properties, and more. They can be used in any framework.
- slots allow for easy element nesting (Lit: Working with Shadow DOM)
- parts allow external manipulation of CSS.
- events make critical information available outside of a component.
Alongside the documentation for Styles and Components, we also present Samples and Patterns. These differ in their scope:
- Samples: Tied to a specific component, these show its use in a particular context. They are added as "Sample" stories in the component's documentation.
- Patterns: More advanced, they demonstrate how to combine several components to solve a specific problem. They are added as stories in the "Patterns" section.
The Shoelace web component library is our working inspiration. Components are copied directly from their source code and pasted in the packages/components/src/_components folder.
There may have been updates since the files there were copied to our repo! In those instances, copy the updated component folder from the Shoelace repository and use that as a starting point.
Additionally we have taken things like the FormControlController directly from Shoelace and are slowly adapting them to our needs. If something is broken, missing, or working in an unexpected manner, there may be things that were missed / misconfigured / not yet addressed in our library.
A good rule of thumb: when in doubt, refer to Shoelace!
We present the library in a Storybook with the following sections:
- DOCS: All .mdx documentation files.
- COMPONENTS: Web Components built with Lit JS. Often more complex than Styles, and could feature reactivity, state, multiple slots, properties, and more.
- UTILITIES: Web Components built with Lit JS, used as SDS-internal helper components. Technically necessary to build other components and generic enough to be used multiple times. Not officially part of the design system library and no respective component existing in Figma.
- STYLES: These are standalone CSS files. They don't provide any logic and are often non-interactive.
- PATTERN: Demonstrate how to combine several components to solve a specific problem.
Each component / utility / style / pattern contains both docs and stories:
The docs serve as a quick interactive reference for developers. Comments at the top of each component file and above properties and methods are automatically compiled into the docs.
@propertydecorators appear in the Storybook "ATTRIBUTES" section@slotdecorators appear in the Storybook "SLOTS" section@csspartdecorators appear in the Storybook "CSS SHADOW PARTS" section@dependencydecorators appear in the Storybook "PROPERTIES" section under "dependencies".@statedecorators appear in the Storybook "PROPERTIES" section. These should generally be be marked with the JSDoc annotation/** @internal */so they do not appear in the docs.@eventdecorators appear in the Storybook "EVENTS" section
The individual stories should attempt to show the component in every possible visual state for quick visual testing with Chromatic.
Ask yourself: "How many visual states can this component or style have and in which combinations?" Attempt to write stories that concisely present these visuals states.
We have a limited number of "runs" meaning every time an active Pull Request branch is pushed to, we pay for Chromatic to analyze each story. Therefore, we try to limit the amount of stories written and avoid excessive pushes to active PR branches.
To make things easier, @mariohamann has authored some Storybook Helpers
These will allow you to do things like present various properties along two axes for quick visual comparison.
If you are working on a component, follow the steps below:
- Move the component folder from
packages/components/src/_componentstopackages/components/src/componentsor run$pnpm plopto generate a blank component template. - Open the component's Storybook Docs or default Story. Ensure this is working properly. You'll want to have a place to observe the component as you work.
- Check the Shoelace repo components folder for the latest published component code. If you need to re-copy updated source code, ensure you copy the whole component folder not just the component file (includes tests and styles) AND rename contained imports, variables, components etc... prefixed with
sltosd(e.g.sl-componentbecomessd-component) and likewiseShoelacetoSolid(e.g.ShoelaceFormControlbecomesSolidFormControl). - Remove any properties from the copied Shoelace code that are irrelevant to our design (e.g.
pillis a re-occurring prop in Shoelace that alters a component's border radius, our designs do not offer this). Refer to the Figma design documentation for the component you are working on. - Compare the old UI component to the newly adapted Shoelace component. Refer to the UI Component Library to get an idea of what is being changed. This helps to see what is being lost or improved upon and should be summarized in the migration guide.
- Keep the technical props and features of the Shoelace component that feel relevant. It is easier to decide which ones can be removed at the end.
- Convert the component styles to use a Tailwind first approach. Shoelace does not use Tailwind and includes CSS files for every component. These should be carefully inspected and adapted. Work your way through the render() method of the component and remove CSS classes one by one, replacing them with a combination of Tailwind classes that implement our design. Keep in mind our designs may differ from the original styles applied by Shoelace, however, there are many small details (regarding
display,position, or interaction states etc.) that should be carefully observed and adapted. - Mobile First Approach. We as design system do not consider in detail on which device our components will be used as we want to be as generic as possible. However, we still build our components following the Mobile First approach (eg. using mobile tokens as default).
- Implement any missing behavior. Once the Shoelace component has been reduced and re-styled with Tailwind, add any missing functions that may be necessary to meet the component's requirements.
- Write concise comments build up the auto-generated Storybook docs. We rely primarily on the docs to communicate to the library users (developers). Write descriptive comments and organize properties semantically to the best of your ability.
- Write concise Storybook stories to cover all visual scenarios. See the Storybook section above for further information. All stories can furthermore be observed together in the docs.
- Start with the jest tests from Shoelace. Inside of
packages/componentsyou can test individual components withpnpm test.component input(where input is akin to the sd-input component). These will likely contain some misnamed properties or improper default values. Adapt them as needed to fit our use case. - Add any tests that are needed for new component behavior. Motto: “Test the behavior, not the implementation.” Write tests that verify your components meet the expected requirements and specifications, ensuring they function correctly from the user's perspective. Don’t get too tied up trying to test all the technical details.
- Author the full migration guide. The migration guide should be placed in the
packages/components/src/docs/Migrationfolder. The migration guide should be based on the migration guide template (templates/migration-guide-template.mdx) and be named by the old component name (e.g. ui-button.mdx).
Run pnpm verify in the root directory before creating a PR. This will check that all formatting, tests, and build processes are working correctly to allow the pipeline to run successfully.
If you are working on a style, follow the steps below:
- Create new styles in the
packages/components/src/stylesfolder. - Set up a Storybook story alongside the styles, using a default story. This allows you to preview and iterate on the styles as you work.
- Each style should have an accompanying declaration file. This is for documenting the style and its attributes. Follow the structure of our existing styles for guidance (eg: sd-meta).
- Import your styles into the
packages/components/src/solid-styles.cssfile. This step is crucial for enabling other Solid components to access the new styles.
_ You can always refer to the existing components and styles to familiarize yourself with the workflow!_
In our security workflow, Renovate (GitHub App) automatically identifies and updates security issues in our project dependencies.
Renovate also creates a “Dependency Dashboard” ticket to track all found updates. During each iteration, we plan and assign the dashboard ticket to a specific team member. The assigned team member has to update the described packages by runing pnpm update all, creating a corresponding PR, and finally closing the ticket. This process ensures efficient handling of security updates while maintaining clear accountability within the team.
packagescomponentssrc_components: components previously copied from Shoelace that have replaceslprefixes withsdprefixescomponents: Primary folder containing our Web Components. Added as stories in the "COMPONENTS" section.accordion: Lit JS web component that implements an accordion. The comments are automatically compiled into the Storybook docs and should be used for user clarification.accoridion.tests.ts: Suite of jest tests for the accordion component. Critical for deployment and maintenance.accordion.stories.ts: Collection of Storybook stories that are primarily used for visual testing with Chromatic. Any samples are added as stories here.
docs: all ".mdx" doc files that appear in the "DOCS" section of our Storybookmigration: Individual component migration guides
internal: A set of utilities that are reusable internally. Check here should you need something like a debounce, it may have already been implemented.patterns: Demonstrate how to combine several components to solve a specific problem. Added as stories in the "PATTERNS" section.styles: These are standalone CSS files. They don't provide any logic and are often non-interactive. Added as stories in the "STYLES" section.
- pnpm
- Web Components
- Lit JS
- Tailwind
- Storybook
- Jest
- Chromatic
- Vite
- PostCSS
In addition to Storybook, a Figma library that serves as a reference for design guidelines, components and patterns used in this project, covers the design part of the SDS.
In the onboarding for designers, we also provide an overview on the figma file structure to better understand the design system and its components.
After defining our own principles and decided for the name Solid Design System, we realized the close connection to SOLID Design Principles, a set of five design principles that aid in designing robust, testable, extensible, and maintainable object-oriented software systems. Each principle addresses specific challenges in software development.
These principles are not developed by us and the connection is more 'unintentional'. Nevertheless, the strong and deep connection between our principles and the ones mentioned above is definitely worth sharing here and we highly recommend to get familiar with them as well.