mineral-ui / mineral-ui Goto Github PK

View Code? Open in Web Editor NEW

556.0 25.0 48.0 14.73 MB

A design system and React component library for the web brought to you by CA Technologies.

Home Page: http://mineral-ui.netlify.com

License: Apache License 2.0

JavaScript 99.33% HTML 0.27% CSS 0.40%

mineral-ui react design-systems components accessibility

mineral-ui's Introduction

Mineral UI

Mineral UI is a design system and React component library for the web that lets you quickly build high-quality, accessible apps.

ℹ️▶️ Please read: Important updates regarding the status of this project

Project Goals

Consistent, thoughtful design
Accessible and inclusive
Performant
Responsive
Powerful and easy to develop with inside your app

Getting Started

Installation

Install the Mineral UI package and its dependencies.

npm install mineral-ui emotion-theming @emotion/core @emotion/is-prop-valid @emotion/styled react react-dom

yarn add mineral-ui emotion-theming @emotion/core @emotion/is-prop-valid @emotion/styled react react-dom

Usage

import React from 'react';
import { render } from 'react-dom';
import Button from 'mineral-ui/Button';
import { ThemeProvider } from 'mineral-ui/themes';

function App() {
  return (
    <ThemeProvider>
      <Button>
        Hello World
      </Button>
    </ThemeProvider>
  );
}

render(<App />, document.getElementById('app'));

Your app must be wrapped in a ThemeProvider at its root in order for the styles to apply correctly.

Also, please see our import syntax guide.

Open Sans Font

Mineral UI was designed around Open Sans. To get the components to look right, you will need to include this font in your project yourself or our styles will fall back to system fonts. To quickly include this font in your app, copy this code into the <head> of your HTML document.

<link href="https://fonts.googleapis.com/css?family=Open+Sans:300,300i,400,400i,600,600i,700,700i,800,800i" rel="stylesheet">

For more options loading this font from Google, check out the Selected Family popup, in the specimen. You can also download the font file and serve it yourself if you'd like, but we'll leave that to you.

Styling

This project uses CSS-in-JS and Emotion for component styling. Refer to the styling page for details.

Questions

If you have read through the documentation but are still facing difficulties, we are happy to help. Please reproduce your error by forking our Mineral UI Starter and adding the relevant code there. Then, send us a message on the Flowdock "Mineral & Styleguide" Flow or open an issue including the relevant link.

Contributing

We welcome all contributors who abide by our Code of Conduct. Please see the Contributors Guide and Developer Docs for more details on submitting a PR, setting up a local dev environment, running tests, etc...

How You Can Help

All of the work for this project is accomplished via pull requests and issues. You can submit a PR or issue to:

Update components (PR)
Update tests (PR)
Improve documentation (PR)
Suggest a change/improvement/feature (issue)
Report a bug (issue)

Thank you for offering your time, expertise, and feedback. It’s greatly appreciated!

Versioning

Until this project reaches a 1.0 milestone, minor version numbers will simply be incremented during each release. The Changelog will continue to document the different types of updates, including any "breaking changes".

After the 1.0 milestone, this project will follow SemVer.

Browser Support

Mineral UI supports the latest versions of Chrome, Firefox, Safari, Edge, and Internet Explorer 11.

Roadmap

Future plans and high priority features and enhancements can be found on the Roadmap.

License

This project is licensed under the Apache 2.0 License — see the License file for details.

mineral-ui's People

Contributors

Stargazers

Watchers

Forkers

wendyjm alternatekev ramana459 trotzig junedomingo brentertz marufsiddiqui jackthailand victoriavasys jaroslawsawicki agentkma divseb nayosx nullnotfound charlklein trendingtechnology calthomson sheelarajeshkumar sughanpandita marcintreder impactbyte-design gioalvaro colemanto indigos33k3r enisen djjimmyhd nazartrynko dehamilton jgiri20 avetisk rahulmeshram zeplo mikewaite targetx trevdor copewood moonpiano gsklee jyotsnac blackbriar fdelacruzsoto themesexpert1986 forkkit markhougaard nelsonpecora ssossou shippool

mineral-ui's Issues

An in-range update of react is breaking the build 🚨

Version 15.6.1 of react just got published.

Branch	Build failing 🚨
Dependency	react
Current Version	15.6.0
Type	peerDependency

This version is covered by your current version range and after updating it in your project the build failed.

As react is “only” a peerDependency of this project it might not break production or downstream projects, but “only” your build or test tools – preventing new deploys or publishes.

I recommend you give this issue a high priority. I’m sure you can resolve this 💪

Status Details

✅ continuous-integration/travis-ci/push The Travis CI build passed Details
✅ greenkeeper/verify Greenkeeper verified pull request Details
✅ license/cla Contributor License Agreement is signed. Details
✅ continuous-integration/travis-ci/pr The Travis CI build passed Details
❌ VersionEye Some dependencies have no license. Details

Not sure how things should work exactly?

There is a collection of frequently asked questions and of course you may always ask my humans.

Your Greenkeeper Bot 🌴

[Component Strategy]: Implement flow typing

Expected behavior

Components use flow typing. PropTypes are exported. Flow type files are exported as es modules.

Current behavior

There is no typing an no PropTypes.

Context

Typing will help consumers understand the component APIs.

connect #31

[Site] should not generate es modules

As a Mineral UI developer, I want to update the site package to not generate es modules as they are unnecessary. They take extra time to build and are also getting deployed to the website unnecessarily.

AC:

Site package does not create es modules
mineral-ui.github.io does not include es folder

[TextInput] identify all other types

[Site] Home page IA

As a consumer, I want an attractive, useful homepage to greet me when visiting the site so that I feel like Mineral UI is a professional product and can quickly find what I need.

AC:

Survey peer design system site homepages
Create IA doc
Possibly create wireframe

[Flow] Custom Types

As a consumer using Flow, I want to understandable Flow types in Mineral. I would like to not have to define custom types.

AC:

MnrlReactNode and other custom flow types should show up as standard react flow types
Consumers do not get flow errors for our custom types.

Other Considerations:

Button icon props use react $element should they use Mineral types
check in with Brent before pulling.
We may want to publish our types to flow-typed
Likely to remove custom types and duplicate/replace definitions

[Icon] component

As a mineral-ui consumer, I would like an Icon component, so that I can easily add icons to my application.

AC:

Provides material design icons
Individually consumable icons
- Can import 1 icon and not have to download all of them
Allows for different colors
Allows for different sizes
Allows user to pass in own SVG
Documentation updated
Demos added to site

Other considerations:

https://css-tricks.com/lodge/svg/
Npm package - https://www.npmjs.com/package/material-design-icons
Should we provide a core set of icons to alleviate need to multiple imports?
- Mike Waite suggested
- Not sure if this provides much value - seems like app could handle this with a simple wrapper if needed
Renders inline svg tags
Likely implementation
- build:icons script
  - Iterates svgs from material-design-icons
    - Creates react component per icon
      - Based off component template
    - Creates index.js of individual named exports
- A possible alternative might be to use dynamic import() statements to import respective svg based on a prop, thus allowing a single Icon component
A11y
- RTL - http://google.github.io/material-design-icons/#icons-in-rtl
- title/desc
- ariaLabelledBy
- ariaHidden
- role presentation vs image vs icon
How does it work with Button component?
Theme variables?
There are a lot of icons. If categories are provided, they should be maintained for organization in the demo.
SVGO

Prior art suggested by Kyle

[Component Strategy] Interview Stakeholders

As a Mineral UI developer, I want to investigate possible implementations for future development of components and styles, so that we provide components that meet consumers needs and are maintainable.

AC:

Discuss considerations with consumers

Considerations:

See document for considerations
https://docs.google.com/document/d/1uQYXaQhiioUCzcIgjZxWXeM7jzpgmVRy1We6wwSlEp4

[Webpack] Consider moving to `webpack-config-ca` package

Description

It may be worth thinking about utilizing common CA packages, such as https://github.com/CAAPIM/webpack-config/ and https://github.com/CAAPIM/eslint-config-ca/, since they are used by other CA projects, which will be using the Mineral UI component library.

If Mineral UI is built without incorporating these packages, it likely won't function properly with other CA products when it comes time to use Mineral components.

[Card] initial component

As a consumer, I want a Card component, so that I can lay out content that belongs in a card.

AC:

Typography
Color
Spacing
States
Variants
A11y

Other Considerations:

Consider basic Card content, header, image, and actions (footer) separately, but in a cohesive manner

[Form][TextInput] new components

As a product developer, I want to use text inputs in my product that follow the guidelines set by the CA Style Guide.

AC

A Form component provides layout and onSubmit
A TextInput takes user input
support types ('date','datetime-local','email','month','number','password','tel','text','time','url','week')
Riley and Wendy go over the docs

Considerations

Other components to be split out as needed

Link to styleguide: https://ca.invisionapp.com/d/main#/console/11070131/250301098/preview
Work on this story has been started and is available here https://github.com/mineral-ui/mineral-ui/tree/137-text-input-deux
other input "types" (radio, checkbox, etc......)

[Button] Support Icons

as a consumer, i want icons in my buttons

HYPOS:

composition will work
passing icons in on props will work better

Considerations:

RTL languages

connect #174

Action required: Greenkeeper could not be activated 🚨

🚨 You need to enable Continuous Integration on all branches of this repository. 🚨

To enable Greenkeeper, you need to make sure that a commit status is reported on all branches. This is required by Greenkeeper because we are using your CI build statuses to figure out when to notify you about breaking changes.

Since we did not receive a CI status on the greenkeeper/initial branch, we assume that you still need to configure it.

If you have already set up a CI for this repository, you might need to check your configuration. Make sure it will run on all new branches. If you don’t want it to run on every branch, you can whitelist branches starting with greenkeeper/.

We recommend using Travis CI, but Greenkeeper will work with every other CI service as well.

Publish Packages & Deploy Site

As a consumer I want to see where we are with the button component.

AC:

Buttons published
Site shows docs in current state
Other Packages Published
Review changelogs

Other considerations:
Think about how the PR should be executed.
Family Style pairing.

[Site] Refactor site/demo structure

As a mineral ui developer, I want to refactor the site/demo structure to avoid circular dependencies and to better structure documentation, to make things easier to maintain.

Connects #46

[Site]: Investigate prop documentation options

Remove Hello and World and HelloWorld components

As a mineral-ui developer, I would like to remove the no longer needed starter components, namely hello, world, hello-world.

Removed from packages
Removed from site
Documentation updated

Other considerations

Send email to npm and ask for them to be removed/unpublished

[Site] Demo Architecture

As a Mineral UI developer, I want site demos optimized for reuse.

AC:

Site demos are separate from component examples

Other Considerations:

React Storybook

[Button] User Testing

As a team, we'd like to test some assumptions we made about our component structure.

AC:

How do consumer devs feels about our component structure?
Is there any feedback that requires more work on our end?
In doing this work, document how to write this story better in the future.

Action required: Greenkeeper could not be activated 🚨

🚨 You need to enable Continuous Integration on all branches of this repository. 🚨

Since we did not receive a CI status on the greenkeeper/initial branch, we assume that you still need to configure it.

We recommend using Travis CI, but Greenkeeper will work with every other CI service as well.

[Card] actions

As a consumer, I want a considered, flexible "actions" section of the Card component, so that I can make the best use of it.

Blocked on pending design decisions. Core issue illustrated here: https://codepen.io/anon/pen/qjGNVq

Also blocked on lack of Layout component

AC:

Section accepts button children
Section holds the expand/collapse trigger for the card
Section plays well with other sections

Dependency management

As a Mineral UI developer, I would like to keep dependencies updated, so that the codebase does not fall behind.

Background:

Planning and working on features does not readily surface the need for regular maintenance tasks such as keeping dependencies updated. We need a way to increase the visibility of this task.

AC:

Configure Greenkeeper.io
Update dependencies

Other Considerations:

Greenkeeper
VersionEye
David

[Theme] Variable/naming schema

As a Mineral Developer, we need to create a system of variables that tackles size, colors, fonts etc.

AC:
Variables for:

Size (sizes, margins, padding)
Colors
Borders
Theme Families (violet vs teal)
Fonts
Elevation
Shadows
Timing
Easing

Themes are created from a file of shared variables (e.g. a theme maps the color palette to intent: primary, success, warning, etc...).

[TextArea] initial component

As a product developer, I want to use text areas in my product that follow the guidelines set by the CA Style Guide.

Link to styleguide: https://ca2.invisionapp.com/d/main#/console/11070131/235066870/preview

Design Questions

text area size small (like textInput)
read only with variant should not be colorized
are icons allowed in text areas?

AC:
Schema for component considerations
Things needed for a "text area" component:

Typography
- currently looks like Open Sans
- system font fall back
- need font-sizes to map to sizes
- need weights
Color
- should be a single style/color with states for error and other outliers
Spacing
- map to same as button spacing
~~Icons~~
- n/a
Animation
- not yet?
States
Size / Shape
Variants (kinds)
A11y
Development Docs (props, code, examples)
Design Docs (usage, philosophy, patterns)

Considerations:

We should probably think about what an MVP of this component is.

[Docs] Define what constitutes a breaking change

Link to it in the PR template for clarity

[All] Remove leftover cruft

As a Mineral UI developer, I want my code to be rid of cruft so that I don't have to look at it while I'm trying to write good code.

AC:
Cruft is gone

[Site] Add routing

As a Mineral UI consumer, I would like a way to directly link to components on the demo site, so that I get to specific pages without needing to navigate from the home page.

As a Mineral UI developer, I would like routing in the site, so that it is easier to manage, matches the design, has readable urls, is bookmarkable, etc.

AC:

Route for each component
Update component README's to point to permalink

Other Considerations:

Site is currently deployed as an SPA
- We either need to
  - statically generate the files prior to deploying
  - use github 404 page to redirect 404 to root and use push state router
  - switch to Netlify - which supports both redirects and static deploy

Update Milestones

As a contributor, I want to know what milestone i'm working toward

AC:

Github Milestones and Roadmap.md file reflect reality
existing issues are tied to a milestone if applicable

Other Considerations:
Revisit the "goals" titles (lol increments)

[Button] Design Docs

As a consumer, I want design docs so that I know when to use it and how to adhere to the styleguide as I build my app.

AC:

Design Docs (usage, philosophy, patterns) -- get from Aaron??

Stakeholder Transparency

As a Mineral UI stakeholder, I would like more transparency into what the team is currently working on and the direction the product is going, so that I can make informed decisions.

AC:

Create public facing kanban board for work items
- Add stories from AC to Github issues
- Add links github issues in AC stories
Add GitHub milestones and categorize stories/PR's
Update repo documentation
- Link to kanban board
- Update Roadmap.md

Other considerations:

Are we using waffle or github projects/milestones
Take a look at us standards design system roadmap for ideas on roadmap presentation https://standards.usa.gov/whats-new/product-roadmap/

Figure out and apply sizing strategy

Expected behavior

As a consumer, I want Mineral UI components to be sized properly no matter how my app is styled.

Current behavior

Because our components use rems for sizing, they are dependent on the app environment in which they are placed.

Possible solutions

Documented here, along with a recommendation: https://docs.google.com/document/d/1dCdAJBjPLLh_9O4FlsmWrZf1zrgWA0cBEUbNnfQa2hI/edit#

Steps to reproduce (for bugs)

Place a Mineral UI component in an app with the following style, html { font-size: 62.5%; } (e.g. sombrero)
Notice that the component is much too small

[Card] additional contents ie charts

[Component Strategy] Recommendations

AC:

Discuss recommendations with consumers and gather consensus
Write up a research results document

Considerations:

See document for considerations and recommendations
https://docs.google.com/document/d/1uQYXaQhiioUCzcIgjZxWXeM7jzpgmVRy1We6wwSlEp4

[Site] Code example

As a Mineral UI consumer, I want code examples in the site, so that I can quickly understand how to use the components.

AC:

Syntax highlighting
Code matches prop demo example

Other considerations:

Live editable code

[Theme] Figure out @font-face

as a consumer, i want to get the fonts referenced in the styles into my app so that i conform to the style guide.

HYPOS:

people won't want to load from google fonts
people will notice that they're not using the right font

AC:

consumers can figure out how to put open sans in their app.
consumers app will fallback to system fonts if they don't build in the font
fonts have been applied to the site package

Considerations:

threepointone/glamor#40
see material-ui README for example

[validation] for TextInput, TextArea, others?

[Site] IA for Component Page

As a consumer, I would like the information about a component to be available and laid out in a helpful, understandable manner.

AC:

Create an IA document and wireframe that demonstrates content strategy for a single component.
Documents have been reviewed by potential consumers.

[Site] Create Theming page

As a consumer of or contributor to Mineral UI, I want a page to explain theming, so that I understand this core concept.

AC:

Create the page
Content should make clear:
1. What is a theme?
2. Under which circumstances should a consumer modify it?
3. How should the consumer do so?

Other Considerations:

Maybe grab most of the content out of Styling.md?
Is this where theme variables (tokens) should be documented?

[Component Strategy] MVP implementation

As a Mineral UI developer, I want to implement the preferred component/styling strategy that resulted from the #21 spike, so that we provide components that meet consumers needs.

AC:

glamor/glamorous

[Site] Style component page

As a consumer, I want a nice looking component page that has the information I need and is laid out in a useful manner.

AC:

page is laid out
clear hierarchy
prop docs are styled
props are laid out in an informative way
examples are distinct

Considerations:

required values
prop type
prop description
future automation

[Card] title

As a consumer, I want considered, flexible "header" and "image" sections of the Card component, so that I can make the best use of it.

AC:

Header section accepts proper combinations of title, subtitles, etc...
Sections play well with other sections

Integrate Contributor License Agreement into Github workflow

As a member of the legal department, I want contributors to sign a CLA, because reasons.

Uses CA CLA
Greenkeeper bot can be approved and PR's can be accepted

Considerations

[TextInput] number type

[Site] CNAME

As a Mineral UI developer, I want to use the mineral-ui.com custom domain for the project site.

Background:

The custom domain has already been setup and is working.
Manually setting the domain via the mineral-ui.github.io github settings commits a CNAME file to the repo. During the next site deploy, it will however be overridden/erased.

AC:

Site package contains CNAME file for mineral-ui.com that gets copied to dist during build and deployed along with any other site assets
mineral-ui.com continues to work as expected

[Button] initial component

As a Mineral UI developer, I want to develop a button component to validate our infrastructure and development experience.

Link to styleguide: https://ca2.invisionapp.com/share/9MBRILWTW

AC:

The button we build will handle Aaron's styleguide's specs for:

Typography
- currently looks like Open Sans (font file won't be provided yet)
- system font fall back
- need font-sizes to map to sizes
- need weights
Color
- map theme colors to kinds & states
Spacing
- map to sizes?
States
Size / Shape
- how many? 3?
Variants (kinds) -- come up with a better word
A11y
Document any other relevant API updates

[Archetype] Tool for generating new components

Just capturing this for later use. Seems like https://plopjs.com/ could be a really useful tool to build this out.

[Component Strategy] Spike Implementation

AC:

Investigate leading solutions
- styled-components
- glamorous
- fela
- other?
Experiment with code in mineral-ui
- abstract underlying implementation so that css-in-js solution may be swapped
- base components
- public props API
- themes
- DX
  - debugging styles
  - HMR
- writing tests
  - including snapshot tests
- Requirements placed on consuming app

Considerations:

See document for considerations
https://docs.google.com/document/d/1uQYXaQhiioUCzcIgjZxWXeM7jzpgmVRy1We6wwSlEp4

[Site] Site Map for Demo Site

As a designer, I would like to know what pages, content and workflows I can expect from our demo site.

AC:
Create a sitemap that accounts for all the things listed in our card sorting exercise. Consider our user personas and create additional pages for their needs.

Considerations
Think about workflows from page to page to enhance the UX of our site.

[Sticky] Component master list

Schema for component considerations:

Link to styleguide: https://ca2.invisionapp.com/share/9MBRILWTW

1. Typography
2. Color
3. Spacing
4. Icons
5. Animation
6. States
7. Size / Shape
8. Variants (kinds)
9. A11y
10. Development Docs (props, code, examples)
11. Design Docs (usage, philosophy, patterns)

[Button] Development Docs

As a consumer, I want development docs so that I know how to use it in my app.

AC:
The following docs are created:

Development Docs (props, code, examples)

Considerations:

Reference the result of the site IA issue

mineral-ui / mineral-ui Goto Github PK

mineral-ui's Introduction

Mineral UI

Project Goals

Getting Started

Installation

Usage

Open Sans Font

Styling

Questions

Contributing

How You Can Help

Versioning

Browser Support

Roadmap

License

mineral-ui's People

Contributors

Stargazers

Watchers

Forkers

mineral-ui's Issues

Version 15.6.1 of react just got published.

Expected behavior

Current behavior

Context

Description

AC

Considerations

AC:

Other Considerations:

Design Questions

Expected behavior

Current behavior

Possible solutions

Steps to reproduce (for bugs)

Recommend Projects

Recommend Topics

Recommend Org