Sancho UI
Sancho is a responsive and accessible design system built with React, Typescript and Emotion. Named after the ever-faithful, hilariously acerbic sidekick of Don Quixote, Sancho is designed to help you no matter how quixotic your dreams may be.
View on GithubGetting started
Installation
Install Sancho and Emotion into your React project using yarn or npm.
yarn add sancho @emotion/core @emotion/css
And import the desired components.
import { Button } from "sancho"; function Project() { return ( <Button>Hello world!</Button> ); }
Styling and Emotion
Sancho uses CSS-in-JS and Emotion for styling, and it’s recommended (though not required) to use Sancho within projects that use Emotion. Emotion allows us to style components using the css
prop - a bit like styling elements using the style
prop, but with the added benefit of pseudo selectors and the full power of css. Emotion also provides powerful and predictable composition. This means that you can pass css attributes into our components to override their styles.
/** @jsx jsx */ import { jsx } from "@emotion/core"; import { Button } from "sancho"; function MyCustomButton() { return ( <Button css={{ color: "red" }}>I have red text!</Button> ); }
Most Sancho components provide BEM-style class names. This allows you to style nested elements within components.
/** @jsx jsx */ import { jsx } from "@emotion/core"; import { Alert, useTheme } from "sancho"; function MyCustomAlert() { const theme = useTheme() return ( <Alert title="Hello world!" css={{ maxWidth: "100vw", "& .Alert__bar": { display: "none" }, "& .Alert__content": { padding: theme.spaces.sm } }} /> ); }
For a full explanation of why Emotion was chosen, read this blog post. You can learn more about using the css
prop on the Emotion website.
Theme
Sancho uses a main theme
object which contains global theming variables related to typography, color, spacing, and breakpoints. To access the theme, use the provided useTheme
hook. View the default theme here.
/** @jsx jsx */ import { jsx } from "@emotion/core"; import { useTheme } from "sancho"; function Component() { const theme = useTheme(); return ( <div css={{ padding: theme.spaces.sm, color: theme.colors.text.muted, [theme.mediaQueries.md]: { padding: theme.spaces.md } }} > Hello world </div> ); }
The default theme comes with a dark and light mode. You can use DarkMode
and LightMode
to toggle between the two.
/** @jsx jsx */ import { jsx } from "@emotion/core"; import { DarkMode, LightMode } from "sancho"; function Component() { return ( <DarkMode> <Text>This text will be white</Text> <LightMode> <Text>But this text will be dark</Text> </LightMode> </DarkMode> ); }
You can customize the default theme by overriding its properties.
The example below uses palx and generateColorsFromScales
to create a custom color palette. We also
override some font properties.
import { generateColorsFromScales, ThemeProvider, defaultTheme } from "sancho"; import palx from "palx"; const scales = palx("#08e"); const colors = generateColorsFromScales(scales); const theme = { ...defaultTheme, ...colors, fonts: { ...defaultTheme.fonts, sans: "Roboto, sans-serif", base: "Roboto, sans-serif" } }; function App() { <ThemeProvider theme={theme}> <MyAppContents /> </ThemeProvider> }
For performance reasons, the custom theme should be constructed outside of the React render cycle or memoized using something like useMemo
.
Example projects
Prior art
Sancho originally started as a fork of Evergreen but has since evolved to incorporate my favourite ideas from Bootstrap and Material-UI. We make substantial use of Reach-UI where possible to ensure proper accessibility. This project is obviously hugely indebted to all of these projects.
About
This project is mainted by Ben McMahen and sponsored by Watershed.