{"id":13673381,"url":"https://github.com/TheMightyPenguin/dessert-box","last_synced_at":"2025-04-28T09:30:36.203Z","repository":{"id":37631450,"uuid":"363806113","full_name":"TheMightyPenguin/dessert-box","owner":"TheMightyPenguin","description":"An utility to create a Box component from your vanilla-extract + sprinkles tokens.","archived":false,"fork":false,"pushed_at":"2023-07-26T19:34:31.000Z","size":44255,"stargazers_count":349,"open_issues_count":7,"forks_count":20,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-04-19T12:24:19.371Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/TheMightyPenguin.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2021-05-03T03:25:17.000Z","updated_at":"2025-03-23T07:02:36.000Z","dependencies_parsed_at":"2024-01-07T21:05:09.248Z","dependency_job_id":"e523a864-f308-4eda-a050-5e183c071581","html_url":"https://github.com/TheMightyPenguin/dessert-box","commit_stats":{"total_commits":52,"total_committers":11,"mean_commits":"4.7272727272727275","dds":0.5769230769230769,"last_synced_commit":"746e9ba797a58dd645a6945579de04341f16dad2"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TheMightyPenguin%2Fdessert-box","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TheMightyPenguin%2Fdessert-box/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TheMightyPenguin%2Fdessert-box/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TheMightyPenguin%2Fdessert-box/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/TheMightyPenguin","download_url":"https://codeload.github.com/TheMightyPenguin/dessert-box/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250699370,"owners_count":21473220,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-02T10:00:39.137Z","updated_at":"2025-04-28T09:30:35.435Z","avatar_url":"https://github.com/TheMightyPenguin.png","language":"TypeScript","funding_links":[],"categories":["Vanilla based Frameworks/Libraries","TypeScript"],"sub_categories":[],"readme":"# 🍰 Dessert Box\n\nA set of utilities to build UI and components with [vanilla-extract][vanilla-extract].\n\n\n- [🍰 Dessert Box](#-dessert-box)\n  - [Installation](#installation)\n  - [Styled](#styled)\n  - [Box](#box)\n    - [Usage](#usage)\n    - [Escape Hatch](#escape-hatch)\n    - [Variants](#variants)\n  - [API](#api)\n    - [createBox(options: { atoms: AtomsFn, defaultClassName?: string })](#createboxoptions--atoms-atomsfn-defaultclassname-string-)\n    - [createBoxWithAtomsProp(options: { atoms: AtomsFn, defaultClassName?: string })](#createboxwithatomspropoptions--atoms-atomsfn-defaultclassname-string-)\n  - [Running the example app](#running-the-example-app)\n  - [How does it work?](#how-does-it-work)\n  - [Thanks](#thanks)\n  - [FAQ](#faq)\n\n## Installation\n\n:warning: If you are not familiar with [vanilla-extract][vanilla-extract], we recommend going trough their docs first and have a working setup before trying any of the dessert box packages.\n\n```sh\n$ npm install @dessert-box/react\n```\n\n## Styled\n\nA `styled-components`-like API to create components in your `*.css.ts` files. To use this, you can define your components\n\n```ts\n// styledComponents.css.ts\nimport { styled } from '@dessert-box/react';\n\nexport const StyledHeadline = styled('h1', {\n  color: 'white',\n  fontSize: '16px',\n  fontWeight: 'bold'\n});\n```\n\n```ts\nimport { StyledHeadline } from './styledComponents.css.ts';\n\nfunction App() {\n  return (\n    \u003cStyledHeadline\u003eI have 0 runtime styles 🤯\u003c/StyledHeadline\u003e\n  )\n}\n```\n\n## Box\n\nA box component that will make consuming your [sprinkles][sprinkles] from a breeze. It provides a zero-CSS-runtime `\u003cBox /\u003e` component (similar to the one in [Braid](https://seek-oss.github.io/braid-design-system/components/Box) or [Chakra](https://chakra-ui.com/docs/layout/box)).\n\n[Try it on CodeSandbox!](https://codesandbox.io/s/dessert-box-demo-wxgy8?file=/src/App.tsx)\n\nIt works by consuming `atoms` created with [`vanilla-extract`][vanilla-extract]) and [`sprinkles`][sprinkles]. Shout out to the team at Seek for making these awesome libraries!\n\n1. Step 1, create your Box with your `atoms` created with sprinkles:\n\n```tsx\n// Box.tsx\nimport { createBox } from '@dessert-box/react';\nimport { atoms } from './sprinkles.css';\n\nconst Box = createBox({\n  atoms,\n  // optional: pass your CSS reset className here\n  // useful if you want to scope your reset to your Box element\n  defaultClassName: 'resetClassName',\n});\n\nexport default Box;\n```\n\n2. Step 2, import it enjoy the sweetness:\n\n```tsx\n// OtherFileOrComponent.tsx\nimport Box from './Box';\n\nconst MyComponent = () =\u003e {\n  return \u003cBox padding=\"large\"\u003eWhat a sweet treat!\u003c/Box\u003e;\n};\n```\n\n**Wondering why using a Box component may be a good idea? or what is a Box component? Check the [FAQ](#FAQ).**\n\n\u003e Wondering how to use `variants` with this library? Check out the [variants](#variants) section.\n\n![dessert-box](https://img.shields.io/bundlephobia/minzip/dessert-box.svg)\n\n[Try it on CodeSandbox!](https://codesandbox.io/s/dessert-box-demo-wxgy8?file=/src/App.tsx)\n\n### Usage\n\nInstall the package:\n\n```\n$ npm install @dessert-box/react\n```\n\nConfigure [vanilla-extract](https://github.com/seek-oss/vanilla-extract) and [`sprinkles`](https://github.com/seek-oss/vanilla-extract/tree/master/packages/sprinkles) and have your atoms ready:\n\n```js\n// atoms.css.ts\nimport { defineProperties, createSprinkles } from '@vanilla-extract/sprinkles';\n\nconst space = {\n  none: 0,\n  small: 4,\n  medium: 8,\n  large: 16,\n};\n\nconst colors = {\n  primary: 'blue',\n  // ...\n};\n\nconst atomicStyles = defineProperties({\n  conditions: {\n    mobile: {},\n    tablet: { '@media': 'screen and (min-width: 768px)' },\n    desktop: { '@media': 'screen and (min-width: 1024px)' },\n  },\n  properties: {\n    padding: space,\n    backgroundColor: colors,\n    // ...\n  },\n  // ...\n});\n\nexport const atoms = createSprinkles(atomicStyles);\n```\n\n\u003e Check `sprinkles` [docs](https://github.com/seek-oss/vanilla-extract/tree/3360bdfc9220024e7ffa49b3b198b72743d4e264/packages/sprinkles#setup) for more context into how to create these atoms.\n\nNow let's create our `\u003cBox /\u003e` using these atoms:\n\n```tsx\n// Box.ts\nimport { createBox } from '@dessert-box/react';\nimport { atoms } from './sprinkles.css';\n\nconst { Box } = createBox({ atoms });\n\nexport default Box;\n```\n\n```tsx\n// otherFile.tsx\nimport Box from './Box';\n\nconst App = () =\u003e {\n  return \u003cBox padding=\"large\"\u003eHello\u003c/Box\u003e;\n};\n```\n\nNotice we can pass every property, shorthand, or condition we can normally pass to our `atomsFn` function. For example, we could leverage the conditions for responsive design we have here:\n\n```jsx\n\u003cBox padding={{ mobile: 'none', tablet: 'small', desktop: 'large' }} /\u003e\n```\n\nIf you need to render a tag different than a `div`, you can use the `as` prop:\n\n```jsx\n\u003cBox as=\"a\" href=\"https://example.com\" padding=\"small\"\u003e\n  Link to example\n\u003c/Box\u003e\n```\n\n### Escape Hatch\n\nWe have a way of specifying an arbitrary value (non design token) for any of your atoms properties like the following:\n\n```jsx\n\u003cBox padding=\"small\" __margin=\"42px\" __backgroundColor=\"yellow\"\u003e\n  Link to example\n\u003c/Box\u003e\n```\n\nThis is useful for those cases where we need to exit our system to accomplish something.\n\n[Try it on CodeSandbox!](https://codesandbox.io/s/dessert-box-demo-wxgy8?file=/src/App.tsx)\n\n### Variants\n\nThe official [@vanilla-extract/recipes][recipes] package has an excelent API for dealing with variants, this can be combined with our `Box` component to create [variant-based components](https://ped.ro/blog/variant-driven-components):\n\nNOTE: (Assuming you already have created your `Box` component following the example above).\n\n1. First define your recipe using the `recipe` function:\n\n```tsx\n// Button.css.ts\nimport { recipe } from '@vanilla-extract/recipes';\nimport { atoms } from '../atoms.css';\n\nexport const buttonRecipe = recipe({\n  variants: {\n    kind: {\n      primary: atoms({ background: 'blue50' }),\n      secondary: atoms({ background: 'yellow' }),\n    },\n    size: {\n      md: atoms({ fontSize: 'large' }),\n      lg: atoms({ fontSize: 'extraLarge' }),\n    },\n  },\n});\n\nexport type ButtonVariants = Parameters\u003ctypeof buttonRecipe\u003e[0];\n```\n\n2. Then use the `recipes` function to create variants and apply them to your `Box`:\n\n```tsx\n// Button.tsx\nimport { Box } from './Box';\nimport { buttonRecipe, ButtonVariants } from './Button.css';\n\ntype Props = {\n  children: React.ReactNode;\n} \u0026 ButtonVariants;\n\nexport const Button = ({\n  children,\n  size = 'md',\n  kind = 'secondary',\n}: Props) =\u003e {\n  return (\n    \u003cBox as=\"button\" className={buttonRecipe({ size, kind })}\u003e\n      {children}\n    \u003c/Box\u003e\n  );\n};\n\nexport default Button;\n```\n\nFor more context, refer to [@vanilla-extract/recipe][recipes] or feel free [to open an issue in this project](https://github.com/TheMightyPenguin/dessert-box/issues/new) if the integration is not working as you'd expect!\n\n## API\n\n### createBox(options: { atoms: AtomsFn, defaultClassName?: string })\n\nCreates a `\u003cBox /\u003e` component that takes atoms at the root level.\n\n```jsx\nimport { createBox } from '@dessert-box/react';\nimport { atoms } from './atoms.css';\n\nconst Box = createBox({ atoms });\n\n\u003cBox padding=\"small\" /\u003e;\n```\n\n### createBoxWithAtomsProp(options: { atoms: AtomsFn, defaultClassName?: string })\n\nCreates a `\u003cBox /\u003e` component that takes atoms as a prop called `atoms`.\n\n```jsx\nimport { createBoxWithAtomsProp } from '@dessert-box/react';\nimport { atoms } from './atoms.css';\n\nconst Box = createBoxWithAtomsProp({ atoms });\n\n\u003cBox atoms={{ padding: 'small' }} /\u003e;\n```\n\n## Running the example app\n\nRun `npm install` then `npm run build` in the root folder (the one with this README file).\n\nThen move into the example folder `cd example` and run `npm install` and `npm start`.\n\n## How does it work?\n\nThis works by depending on build-time generated CSS by [sprinkles](https://github.com/seek-oss/vanilla-extract/tree/3360bdfc9220024e7ffa49b3b198b72743d4e264/packages/sprinkles), and then using the `atomsFn` function to lookup classNames in runtime. So it does have a runtime footprint, but should be pretty minimal. I'm still experimenting to see if it's possible to remove that, but other approaches may lead to other constraints or similar runtime.\n\n## Thanks\n\n- Thanks to the team at Seek for [vanilla-extract](https://github.com/seek-oss/vanilla-extract) and [`sprinkles`](https://github.com/seek-oss/vanilla-extract/tree/master/packages/sprinkles), this would not be possible without these great libs and the technical feats they accomplish.\n\n## FAQ\n\n- What is a Box component?\n\n\u003e It's a generic element that allows you to prototype fast and takes a variety of styling props (think of exposing a lot of CSS attributes as props on a component).\n\n- Why should I use a Box component?\n\n\u003e There are many versions and flavors of a Box component, some are more [flexible](https://chakra-ui.com/docs/layout/box), while others are more [restrictive](https://seek-oss.github.io/braid-design-system/components/Box). The Box in this library falls into the latter category (restrictive), and it's more geared towards being the a lower level API of your Design System (or serving as inspiration for it).\n\nThis Box component is meant to be used as a primitive for consuming design tokens, giving you a nice balance between flexibility and constraints. You can use it as an lower level API to implement your other components (Buttons, Card, Layout components, ...), and also as a prototyping and general usage component:\n\n- As a prototyping tool, it allows you to use all of your design tokens to generate new designs and evaluate if you need to iterate on your foundations, or to validate if they work for your use cases.\n- For general usage you can still have the guarantee that users of your system won't do anything impossible (e.g.: using a value that is not part of the design tokens) but still have a productive experience working on UI.\n\n[sprinkles]: https://github.com/seek-oss/vanilla-extract/tree/master/packages/sprinkles\n[vanilla-extract]: https://github.com/seek-oss/vanilla-extract\n[recipes]: https://github.com/seek-oss/vanilla-extract#recipes-api\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FTheMightyPenguin%2Fdessert-box","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FTheMightyPenguin%2Fdessert-box","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FTheMightyPenguin%2Fdessert-box/lists"}