README
Remarkably's UI Library — Concrete
Note: Converting documentation over to Zeroheight shortly
Table of Contents
Overview
Concrete is the design system (DS) for Remarkably. The whole purpose of Concrete is to define the design principles, style-guide, patterns, content tone, and the rules and specifications of the “reusable” components. Concrete-UI is a branch from Concrete DS and utilizes the design principles and patterns set forth in Concrete to enable both great expereinces for our developers and end users.
The design side of Concrete and Concrete-UI is housed in Figma, and soon will be documented using Zeroheight. The code/development side of Concrete is maintained here on GitHub, and in the minds and computers of our engineering staff.
If you do not have access to the Figma project, please email Eugene to be granted access.
Goals & Design Principles
Concrete was designed and developed with a few goals in mind:
Abstracted
Component and block names shouldn’t be derived from the content they contain, but instead, names should convey structural meaning.Reusable
Components (Button, Text, Icons, etc.) have low complexity and therefore should have high reusability across the platform. They should make no assumptions what page/view they will be used on. Problems solved in one area should be easily applied elsewhere.Mixable
Components should be able to join together to create larger blocks. Blocks will generally have more complexity and lower reusability due to the fact this is where componenets are composed.Powered by variables
All common foundational design elements, such as colors, fonts, spacings, shadows, etc. should be defined using the pre-existing variables and scales in our design system theme. Very rarely you should step outside of what's been defined already.Scalable Systems
Reusing patterns means new elements can be designed and developed faster and with minimal additional CSS.Consistent
Developers will be better able to read each other’s code, and be able to more accurately represent a design which will ultimately contribute to more reliable end-user experiences.Small and DRY
Since we’re reusing low-level components to build larger objects we cut down on CSS bloat. Less code means fewer bugs.All in all... create a delightful designer, developer, and user experience
Establishing a foundation includes defining property values such as color, text, spacing, etc. and where and when to use them. Naming these foundational items is key for onboarding new hires, enabling synchronous design and development cycles, and establishing a point of reference in both Figma and code. Doing so, while bundled in a tight-nit project allows us to create these delightful expriences for our teams internally, and our users externally.
Project Structure
Project Directories
/src: Main directory for components, blocks, containers, utilities, design-sytem themes, and icons.\/blocks: TODO/components: TODO/containers: TODO/ds: TODO/icons: TODO/utils: TODOindex.js: TODO
/assets: Cleans and removes artifacts from the output directory (dist).\/fonts: TODO/icons: TODO
/templates: Cleans and removes artifacts from the output directory (dist).\/blocks: TODO/components: TODO/containers: TODO/icons: TODO
Commands Overview
dev: Run the project, launches storybook in the browser, watches changes in *.stories, watches changes in /icons.
clean: Cleans and removes artifacts from the output directory (dist).
storybook: TODO
prebuild: TODO
build: Build the project to the output directory.
prepublishOnly: TODO
build-storybook: TODO
generate: TODO
icons: TODO
test: TODO
watch:icons: TODO
watch:babel: TODO
webpack: TODO
unit: TODO
update-tests: TODO
Getting Started
Installation
Inside our project, install Concrete UI by running the following:
npm i concrete-ui styled-components @xstyled/styled-components @xstyled/system
# or
yarn add concrete-ui styled-components @xstyled/styled-components @xstyled/system
concrete-ui
Our UI library with theme, components, blocks defention and composition.
styled-components
The underlining library driving the development, styling, and composition of our primitive components.
@xstyled/styled-components
API wrapper used for defining our styled components with a succint nomenclature.
@xstyled/system
API wrapper for styled-system used to maintain chosen nomelcature and allow flexbility when composing components, blocks, and containers.
Including in our project
First, let's wrap our project in our theme provider from Concrete-UI utility directory.
// TODO
Next, let's include
Design Principles
API & Helpful Resources
Composition
Components
Blocks
Containers
Usage Examples
Component Styling
For sake of example, we'll make a very simple button.
// import styled
import styled from '@xstyled/styled-components'
// name our component and define type of element
const Button = styled.button`
// Give our background color property a value from our theme defention using @xstyled/system syntax.
background-color: blue.1;
color: text.white.0;
border-radius: 1;
// Use @xstyled/system syntax to define x and y padding using the scale from our design system.
padding: 2 3;
`