docs: add glossary to specifications

specifications/glossary.md

@@ -0,0 +1,85 @@
+#Stardust Glossary
+
+##Component anatomy
+###Types
+Types are versions of an element that modify the element's standard appearance.
+
+Types cannot be used simultaneously on the same element. For example, "cats" and "dogs" are types of animals, but are mutually exclusive.
+
+<b>Comment</b>: We should use types for defining the standard appearance of the component. What we have so far is using the primary and secondary as types, which in my opinion are variations of the component that are only between themselves mutually exclusive. So, we can define those as enum variation of the component, but sadly we so far come up with the name 'type' for the prop that can be confusing. I propose we change the name of this prop with something like suiStyle (bootstrap has something similar – bsStyle). Should we add here the positive and negative props as well? After this we can use one prop with enum for defining all different types of the component (similar in a way of the shape property in the current [Menu component](https://github.com/stardust-ui/stardust/pull/68)
+
+###State
+States are modifications to an element that help indicate a change in [affordance](http://www.usabilityfirst.com/glossary/affordance/). Common states include loading, disabled, and active.
+
+###Content
+Content are parts which only have meaning in the context of a component. Content use names which describe the type of expected content like header, description, menu, or item.
+
+Content inside a collection or view often includes stubbed versions of other components. For example cards let you use image content, which can be extended by using different variations.
+
+###Variations
+Variations modify qualities of an element like size or color.
+
+Variations are mutually inclusive, and can be used together to modify an element.
+
+##API Design
+###Top Level API
+####Components
+A component is a general term used to refer to any user interface element packaged for distribution (Not to be confused with React’s Component)
+####Shorthand/Children definition
+Most of the components support two ways of definition: shorthand and children. With the shorthand definition we are adding some props to the component in order to define it’s content, in opposite to the children where we are adding the content inside the component, or using some subcomponent. For example: when defining the text displayed in the Button component, we can pass the content prop or we can define the text inside the component:
+```html
+<Button>Click me!</Button>
+<Button content='Click me!' />
+```
+####Subcomponents
+Some of the components have subcomponents defined for passing JSX elements for special parts of the component. For example the Menu components can contain multiple items inside, that can be defined using the Item subcomponent in the following manner:
+```html
+<Menu>
+  <Menu.Item active={activeItem === 'a'} onClick={this.handleItemClick('a')}>
+    Editorials
+  </Menu.Item>
+  <Menu.Item active={activeItem === 'b'} onClick={this.handleItemClick('b')}>
+    Reviews
+  </Menu.Item>
+  <Menu.Item active={activeItem === 'c'} onClick={this.handleItemClick('c')}>
+    Upcoming Events
+  </Menu.Item>
+</Menu>
+```
+###Props API
+####Enum
+We use enum for properties when multiple values are mutually exclusive. We should use the same enums defining the same props across all components for consistency.
+
+####Boolean
+We use boolean for properties when multiple values are mutually inclusive and don’t need any description. This way we are only implying that that property is applied to the component.
+
+##Design language
+
+|Term|Description|
+--- | ---
+type: primary | Used to emphasize a componet's appearance and catch user's attention.
+type: secondary | Used to de-emphasize a component's appearance.
+type: positive ? | Used to hint towards a positive consequence.
+type: negative ? | Used to hint towards a negative consequence.
+children | The primary content of the component.
+content | Shorthand for primary content.
+as | An element type to render as, that can be a function or string.
+className | Additional classes that will be applied to the component.
+size | Used to define different sizes of the component. Comment: Should be standize across all components with values from 0 to 10 for example.
+role | The role of the HTML element generated by the component.
+color | Used for defining specific color for the component, by selecting one of the SUI colors enum.
+inverted | Used to format the component to appear on dark background.
+basic | Used for the component to be less pronounced.
+floated | Used for the component to be aligned to the left or right of its container. ('left', 'right')
+active | Used to style the component showing that it is the current user selection.
+disabled | Used to imply that the component is currently unable to be interacted with.
+loading | Used to make the component show some loading indicator.
+icon | Add an Icon by name, props object, or pass an <Icon />.
+label | Add a Label by text, props object, or pass a <Label />.
+attached | Used for attaching the component to some component. ('left',  'right', 'top', 'bottom')
+compact | Used to make the component take up only the space necessary to fit its content.
+fluid | Used to make the component takes the width from the parent.
+fixed | Used to make the component fixed to a side of it's content. ('left', 'right', 'top', 'bottom')
+textAlign | Align the content. ('left', 'right', 'center', 'justified')
+vertical | Used to make the component display it's content vertically.
+shape | Used to describe the shape of the component. For example for the Menu component, beside the default, we have the following shapes: ('pills', 'pointing', 'underlined')