Skip to content
Sancho UI
Toggle dark mode
Getting started
Components
Helpers
Built with ☕ by
Ben McMahen

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 Github

Getting 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

Captioner
Captioner
Make captions directly in your browser.
View the source
Julienne
Julienne
The easiest way to share recipes with family and friends.
View the source

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.

The Sancho donkey icon is originally based upon work by Martin Berube and the summer vector created by alicia_mb - www.freepik.com