Design System + Theme
Composable UI comes equipped with pre-built components and designs, making it easy to get started with building your composable commerce site.
Additionally, the project includes a Figma design system, which provides a comprehensive set of design elements and guidelines, ensuring consistency and ease of use across your site.
These pre-built components and design resources help you to save time and effort in the development process, allowing you to focus on customizing and refining your platform to meet your specific business needs.
Components and Themes
Composable UI provides React components and layouts that you can use to build your e-commerce solution.
Located in the packages/ui
directory, the @composable/ui
workspace package contains standard re-usable UI components, such as accordions, alert boxes, carousels, gallery, and product cards. The Next.js storefront application in directory composable-ui
uses the basic UI components from @composable/ui
to construct user experiences and components, such as the Cart Drawer, Mobile Menu, Product Listing Pages (PLP), Product Display Pages (PDP), and Checkout.
Composable UI uses Chakra UI to construct all the components and experiences on the Composable UI Storefront. Using Chakra UI enables us to take advantage of a large React UI component library that provides excellent support for accessibility, customization, and support from large community of developers.
Using a component
- To use a component, import the component, reference the component by the name and pass the required parameters as in the following example:
import { ImageBanner } from '@composable/ui'
...
<ImageBanner
image={{
src: '/img/image1.jpeg',
alt: 'image1',
}}
/>
Customizing the logo
- In the
/composable-ui/src/components/logo.tsx
file, define theLogo
component as in the following example:
export const Logo = (props: HTMLChakraProps<'svg'>) => (
<chakra.svg
color="accent"
height="21"
width="auto"
viewBox="0 0 616.56 68.75"
xmlns="http://www.w3.org/2000/svg"
aria-label="Logo"
{...props}
>
After you define the logo component, you can use it in your commerce site by importing the component:
import { Logo } from 'components/logo'
Customizing the favicon
- To change the favicon file, in the
/composable-ui/public/img/favicon.ico
directory, replace the image file. - Update the favicon reference in the
/composable-ui/src/utils/constants.ts
file with the new image name as in the following example:
...
FAVICON: '/img/favicon.ico',
...
Theme Configuration
Composable UI initializes the Chakra UI theme in packages/ui/src/chakra/theme.ts
and constructs the site theme by bringing together several theme files, such as colors.ts
, which are located in the packages/ui/src/chakra/theme/foundations/
directory. The files in directory packages/ui/src/chakra/theme/foundations/
contain the Composable UI theme settings for colours, font sizes, border styles, and more. You can override the default properties, such as the brand colours, default spacing, and font sizes, as required. For example, the packages/ui/src/chakra/colorsPalette.json
file contains the primary and secondary colour configuration, which can modified as desired to match your branding.
For more information on customizing themes, see the Chakra UI Default Theme documentation.
Theme Tokens
Composable UI extends the default Chakra UI theme tokens, by adding theme tokens such as xxs
, xs
, Mobile/XS
, and Desktop/M
for styling your React components. These tokens are defined in the packages/ui/foundations/
directory. The following code sample shows an example to style a text based on the viewport size, and uses Chakra textStyles to apply multiple css properties through a single theme token:
<Text textStyle={{ base: 'Mobile/XS', md: 'Desktop/M' }}>I will be styled with the 'Mobile/XS' textStyle for viewport sizes below the 'md' breakpoint, otherwise I will be styled with the 'Desktop/M' textStyle</Text>
The above textStyles
are defined in packages/ui/src/chakra/theme/textStyles.ts
For more information improving developer experience with Chakra theme tokens, see the Enabling Theme Typing and Autocomplete section.
Enabling Theme Typing and Autocomplete
We recommend generating Chakra UI Types to enable type checking and auto-complete features. This will improve the developer experience when working with Composable UI theme tokens.
To enable theme typing and autocomplete with your theme, run the following command:
cd packages/ui
pnpm install
pnpm themecautionWhen you use
@next/font
in Chakra UI theme configuration, to successfully run thepnpm theme
command, you must ensure thatthe@next/font
assets in thepackages/ui/src/chakra/theme/foundations/typography.ts
file is not included during the execution ofpnpm theme
. You can use the comment tag to disable the assets. For instructions, see thetypography.ts
file.(Optional) To continually auto-regenerate theme typings when a theme file is changed, run the following command:
pnpm theme:watch
Restart the Typescript Server in Visual Studio Code and do the following:
- Press
Command + Shift + P
and view a TS file. - From the drop-down menu, select
Typescript: Restart TS server
.
After performing the above, Visual Studio Code will be type checking with your latest theme token names and values.
- Press
Performance Guidelines
Chakra UI provides an excellent approach to achieving responsive design through Responsive Styles, which removes the need to manually maintain responsive @media
queries in your css. This approach does not rely on JavaScript to support responsiveness to ensure a high performing application.
We recommend avoiding use of Chakra UI's responsive components Show
and Hide
, and the hook useBreakpointValue
, as these impact performance due to the reliance on the execution of JavaScript in the browser to perform responsive UI updates.
- The Show and Hide components
- The useBreakpointValue