github-mirrors/kibana
1
0
Fork 0
mirror of https://github.com/elastic/kibana.git synced 2025-04-23 17:28:26 -04:00
Code Issues Projects Releases Packages Wiki Activity

Document the process for adding components to the UI Framework. (#9660)

Browse source 
Backports PR #9644

**Commit 1:**
Document the process for adding components to the UI Framework.

* Original sha: bc4781687a
* Authored by CJ Cenizal <cj@cenizal.com> on 2016-12-26T19:55:55Z

**Commit 2:**
Explain how to group components in the UI Framework.

* Original sha: 85fe9720f8
* Authored by CJ Cenizal <cj@cenizal.com> on 2016-12-26T21:42:54Z

**Commit 3:**
Add guidance on naming.

* Original sha: 7803490701
* Authored by CJ Cenizal <cj@cenizal.com> on 2016-12-27T00:01:33Z

**Commit 4:**
Cross-link to the CSS style guide.

* Original sha: 42347df85d
* Authored by CJ Cenizal <cj@cenizal.com> on 2016-12-27T19:48:11Z
This commit is contained in:
jasper 2016-12-27 14:49:52 -05:00 • committed by CJ Cenizal
parent 879de8acc3
commit ffb1347f23
1 changed files with 45 additions and 3 deletions
Download patch file Download diff file Expand all files Collapse all files

48
src/ui_framework/README.md
View file

@ -7,9 +7,49 @@
## What is this?
The UI Framework provides you with UI components you can quickly use to build UIs, as well as interactive examples which document how they're supposed to be used. These UI components are currently only implemented in CSS and markup, but eventually they'll grow to involve JS as well.
The Kibana UI Framework provides you with UI components you can quickly use to build user interfaces for Kibana.
When you build a UI using this framework (e.g. a plugin's UI), you can rest assured it will fit into the overall Kibana UI.
The UI Framework comes with interactive examples which document how to use its various UI components. These components are currently only implemented in CSS, but eventually they'll grow to involve JS as well.
When you build a UI using this framework (e.g. a plugin's UI), you can rest assured it will integrate seamlessly into the overall Kibana UI.
## How to create a new component
There are two steps to creating a new component:
1. Create the CSS for the component in `ui_framework/components`.
2. Document it with examples in `ui_framework/doc_site`.
### Create the component CSS
1. Create a directory for your component in `ui_framework/components`.
2. In this directory, create `_{component name}.scss`.
3. _Optional:_ Create any other components that should be logically-grouped in this directory (see below).
4. Create an `_index.scss` file in this directory that import all of the new component SCSS files you created.
5. Import the `_index.scss` file into `ui_framework/components/index.scss`.
This makes your styles available to Kibana and the UI Framework documentation.
#### Logically-grouped components
If a component has subcomponents (e.g. ToolBar and ToolBarSearch), tightly-coupled components (e.g. Button and ButtonGroup), or you just want to group some related components together (e.g. TextInput, TextArea, and CheckBox), then they belong in the same logicaly grouping. In this case, you can create additional SCSS files for these components in the same component directory.
### Document the component with examples
1. Create a directory for your example in `ui_framework/doc_site/src/views`. Name it the name of the component.
2. Create a `{component name}_example.jsx` file inside the directory. You'll use this file to define the different examples for your component.
3. Add the route to this file in `ui_framework/doc_site/src/services/routes/Routes.js`.
4. In the `.jsx` file you created, define examples which demonstrate the component. An example consists of a title, an optional description, an HTML file and an optional JavaScript file. It might help to refer to other examples to see how they're structured.
The complexity of the component should determine how many examples you need to create, and how complex they should be. In general, your examples should demonstrate:
* The most common use-cases for the component.
* How the component handles edge cases, e.g. overflowing content, text-based vs. element-based content.
* The various states of the component, e.g. disabled, selected, empty of content, error state.
## Writing CSS
Check out our [CSS style guide](https://github.com/elastic/kibana/blob/master/style_guides/css_style_guide.md).
## Benefits
@ -23,7 +63,7 @@ Engineers can copy and paste sample code into their projects to quickly get reli
### Remove CSS from the day-to-day
The CSS portion of this framework means engineers don't need to spend mental cycles. These cycles can be spent on the things critical to the identity of the specific project they're working on, like architecture and business logic.
The CSS portion of this framework means engineers don't need to spend mental cycles translating a design into CSS. These cycles can be spent on the things critical to the identity of the specific project they're working on, like architecture and business logic.
Once this framework also provides JS components, engineers won't even need to _see_ CSS -- it will be encapsulated behind the JS components' interfaces.
@ -48,6 +88,8 @@ For a more in-depth analysis of the problems with Bootstrap (and similar framewo
## Examples of other in-house UI frameworks
* [GitHub's Primer](http://primercss.io/)
* [Palantir's Blueprint](http://blueprintjs.com/docs/#components)
* [Ubiquiti CSS Framework](http://ubnt-css.herokuapp.com/#/app/popover)
* [Smaato React UI Framework](http://smaato.github.io/ui-framework/#/modal)
* [Lonely Planet Style Guide](http://rizzo.lonelyplanet.com/styleguide/design-elements/colours)