richard
/
SemanSemantic-UItic-UI
mirror of https://github.com/Semantic-Org/Semantic-UI.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity
Browse Source

Adds lots of docs for styleguide, first draft 

Former-commit-id: 12f9972f35
Former-commit-id: 5a69a596a9
pull/258/head
Jack Lukic 11 years ago
parent
81349d711a
commit
2bbb156db5
4 changed files with 316 additions and 48 deletions
Split View
Diff Options
Show Stats Download Patch File Download Diff File
  1. 138
      node/src/documents/specification/authoring.html
  2. 194
      node/src/documents/specification/cssguide.html
  3. 27
      node/src/documents/specification/htmlguide.html
  4. 5
      node/src/documents/specification/styleguide.html

138
node/src/documents/specification/authoring.html
View File

@ -0,0 +1,138 @@
---
layout : 'default'
css : 'guide'
title : 'Spec Files'
type : 'UI Specification'
---
<div class="segment">
<div class="container">
<h1 class="ui header">Spec Files</h1>
</div>
</div>
<div class="main container">
<h2>Introduction</h2>
<p>Semantic defines an exchange format for user interface. Writing your interface components to match the specifications allows others to easily use your interface components in their project.</p>
<h3>Writing a Spec File</h3>
<p>Before authoring an element you should begin by writing a spec file for your element. A specification file defines the structure and names used inside your element. For more information on naming convention visit our css and html guides.</p>
<p>A spec file also allows you to provide metadata to generate code for your element, this can be used to generate visual documentation of your element.</p>
<h3>Common Specification</h3>
<p>A spec file is a specially formatted json file.</p>
<div class="code" type="javascript">
{
// your element name should be a single word and match to the classname of your element
"Name": "Button",
// you may include metadata
"Author": "Jack Lukic",
"Website": "http://www.semantic-ui.com"
"Version": "2.0",
// All elements must specify whether it is an element, collection, module, or behavior
"Type": "Element",
// definition of the html structure of each type of an element
"Types": {
"Standard" : ".ui.button"
},
// States are ways which elements show an innate change in its quality.
"States": {
"Active" : "active",
"Loading" : "loading",
"Disabled" : "disabled"
},
// Variations are individual classnames which your element may receive to alter its look. Variations should, for the most part, be able to be used together to create more complex styles of an element.
"Variations": {
// If a set of variations are options of a single type (for example sizing may contain, small, medium, etc) then this can be defined as an array.
"Size": [
"mini",
"tiny",
"small",
"medium",
"large",
"huge",
"massive"
],
// Types are exclusive forms of your element. For example a button cannot be an icon button and a text button. The definitions of the html structure of each element is written using emmet syntax. These are used to generate html structures for your elements. For more information visit: http://docs.emmet.io/abbreviations/syntax/
"Types": {
"Standard" : ".ui.button",
"Icon" : ".ui.icon.button > i.icon",
}
"Color": [
"black",
"green",
"red",
"blue",
"green",
"red",
"teal"
],
"Ordinality": [
"secondary",
"tertiary"
],
"Attached": [
"attached top",
"attached bottom",
"attached left",
"attached right"
],
"Circular" : "circular",
"Fluid" : "fluid"
},
// You may define a list of dummy text and selectors which can be filled with them. This is used by generators to export a style guide of your interface element. If you specify an array, each item will be used in order to fill the content of each match.
"Text": {
".ui.button": ["Button", "Click Me", "Lorem Ipsum"]
},
// Your module may optionally include a text definition of its variations to help clarify their purpose. This may include the definition of types or variations
"Definition": {
"Standard" : "A simple button",
"Icon" : "A button icon is formatted to contain only an icon",
"Size" : "A button can vary in size",
"Color" : "A button can have different colors",
"Ordinality" : "A button can blend into a page",
"Attached" : "A button can attach to other content",
"Circular" : "A button can be circular",
"Fluid" : "A button can be fluid"
}
}
</div>
<h3>UI Elements</h3>
<p>A UI element is a basic building block of a website. It may have a singular or group (plural) definition</p>
<div class="code" type="javascript">
{
// in addition to the parameters above an element may contain a definition for its singular and plural type
"Types": {
// these types can only exist for class="ui button"
"Singular": {
"Standard" : ".ui.button",
"Icon" : ".ui.icon.button > i.add.icon",
"Labeled Icon" : ".ui.labeled.icon.button > i.add.icon"
},
// these types can exist only for class="ui button"
"Group": {
"Standard" : ".ui.buttons > .button+.button+.button",
"Icon" : ".ui.buttons > ( (.button > i.icon.user) + (.button > i.icon.heart) + (.button > i.icon.lab))",
"Conditional" : ".ui.buttons > .button+.or+.button",
"Vertical" : ".vertical.ui.buttons > .button+.button+.button"
}
}
}
</div>
</div>

194
node/src/documents/specification/cssguide.html
View File

@ -2,76 +2,116 @@
layout : 'default'
css : 'guide'
title : 'CSS Tips'
title : 'CSS Guide'
type : 'UI Specification'
---
<div class="segment">
<div class="container">
<h1 class="ui dividing header">Style Guide</h1>
<h1 class="ui header">CSS Guide</h1>
</div>
</div>
<div class="main container">
<h2>Writing CSS</h2>
<p>Here's a set of guidelines that may help make writing UI components easier.</p>
<h2>General</h2>
<div class="example">
<h4 class="ui header">Use Border Box</h4>
<p>Border box fixes the box model, and allows padding to be included as part of width and height definitions. Using it opens up another world of possibilities for sizing content to fit fluidly</p>
<h4 class="ui header">Namespace</h4>
<p>All css code must live inside a namespace. By default all ui elements use the class "ui". This prevents rules from altering styles of other content in the page. This also helps differentiate between UI elements and parts of an element</p>
<div class="code" data-type="css">
.ui.two.thingies .ui.thingy {
width: 50%;
padding: 1em;
-webkit-box-sizing: border-box;
-moz-box-sizing: border-box;
-ms-box-sizing: border-box;
box-sizing: border-box;
// incorrect
.menu {
}
// incorrect
.ui.menu {
}
.ui.menu .ui.item {
}
// correct
.ui.menu {
}
.ui.menu .item {
}
</div>
</div>
<div class="example">
<h4 class="ui header">Don't Hyphenate</h4>
<p>All elements are designed to include their own namespace. As long as rules descend from their parent element there is no possibility of rule collision.</p>
<p>Hyphenated class names often describe the intersection of separate concepts, and can be better written to represent each concept separately.</p>
<div class="code" data-type="css">
// no no no
.ui.button-active-red {
background-color: #FF0000;
font-weight: bold;
color: #FFFFFF;
}
// better
.red.ui.button {
background-color: #FF0000;
color: #FFFFFF;
}
.active.ui.button {
font-weight: bold;
}
</div>
</div>
<div class="example">
<h4 class="ui header">Prevent Accidental Highlighting</h4>
<p>Sometimes text can be accidentally highlighted when a user double clicks an element. No need to pull out javascript to solve this.</p>
<h4 class="ui header">No wrappers, no excess markup</h4>
<p>UI elements should be designed to include the minimum footprint of an element. If extra styling is needed, consider using pseudo selectors :after and :before. This allows for the creation of two extra divs inside each div context which can almost always be enough to accomodate extra styling.</p>
<p>If there is no other option than wrapping content in a containing HTML element, consider using a name that describes the content instead of the word wrapper or container.</p>
<div class="code" data-type="css">
.ui.thingy {
-webkit-user-select: none;
-moz-user-select: none;
-ms-user-select: none;
user-select: none;
// not tops
.ui.message .wrapper .title,
.ui.message .wrapper .description {
}
// better
.ui.message .content .title,
.ui.message .content .description {
}
</div>
</div>
<div class="example">
<h4 class="ui header">Joining borders</h4>
<p>Sometimes bordered content must sit next to other bordered content. If each element uses border the borders will double. Consider using either outline or a box shadow to accomplish the same effect but without overlapping borders.</p>
<h4 class="ui header">Grammatical order</h4>
<p>Consider using similar class syntax as if you were actually describing the element in english. Although this is by no means required it may help provide clarity in some circumstances.</p>
<div class="code" data-type="css">
// this might not go so well
.ui.thingy {
border: 1px solid #DDDDDD;
}
// rgba is great, but keep in mind the overlapping borders will be added together to create a darker shade
.ui.thingy {
outline: 1px solid rgba(0, 0, 0, 0.1);
// not perfect
.ui.red.button.pointing {
}
// classic but works
.ui.thingy {
outline: 1px solid #DDDDDD;
// much more semantic
.red.pointing.ui.button {
}
// this works too
.ui.thingy {
-moz-box-shadow: 0px 0px 0px 1px #DDDDDD;
-webkit-box-shadow: 0px 0px 0px 1px #DDDDDD;
box-shadow: 0px 0px 0px 1px #DDDDDD;
</div>
</div>
<div class="example">
<h4 class="ui header">Use Border Box</h4>
<p>Border box fixes the box model, and allows padding to be included as part of width and height definitions. Using it opens up another world of possibilities for sizing content to fit fluidly</p>
<div class="code" data-type="css">
.two.ui.thingies .ui.thingy {
width: 50%;
padding: 1em;
-webkit-box-sizing: border-box;
-moz-box-sizing: border-box;
-ms-box-sizing: border-box;
box-sizing: border-box;
}
</div>
</div>
<h2>Units and Measurements</h2>
<div class="example">
<h4 class="ui header"><em>Relatively</em> Relative</h4>
<p>It's often useful to have multiple sizes of an element. One tip that makes creating resizes easier is to use EMs and relative EMs or rems.</p>
<p>EMs are defined so that 1em is equal to the current font size inside of an element.
<p>EMs are defined so that 1em is equal to the current font size inside of an element. Using EMs can allow you to size content inside an element in proportion to the overall size of the element. Be careful though because this will stack with nested elements</p>
<div class="code" data-type="css">
.ui.thingy {
font-size: 14px;
@ -84,36 +124,88 @@ type : 'UI Specification'
.ui.thingy .thing .thing {
font-size: 2em;
}
// .ui.thingy .thingy should grow as well
.ui.large.thingy {
font-size: 16px;
}
</div>
</div>
<div class="example">
<h4 class="ui header"><em>Absolutely</em> Relative</h4>
<p>REMs are defined so that 1rem is equal to 1 em on the html tag of the page. This is needed to explain how content should be sized related to the overall size of elements on the page</p>
<h4 class="ui header"><em>Recursively</em> Relative</h4>
<p>Using EMs multiplicative nature can often be used to your advantage. Instead of defining multiple tiers of a menu system. Consider using ems for its sizing. As you continue to nest menu elements each nested menu will computer its values with smaller proportions.</p>
<div class="code" data-type="css">
.ui.menu {
font-size: 1rem;
}
.ui.menu .menu {
margin-left: 0.5em;
font-size: 0.9em;
}
</div>
</div>
<div class="example">
<h4 class="ui header"><em>Recursively</em> Relative</h4>
<p>Using EMs however can often be used to your advantage. Instead of defining multiple tiers of a menu system. Consider using ems for its sizing. As you continue to nest menu elements each nested menu will computer its values with smaller proportions.</p>
<h4 class="ui header"><em>Absolutely</em> Relative</h4>
<p>REMs are defined so that 1rem is equal to 1 em on the html tag of the page. This is needed to explain how content should be sized related to the overall size of elements on the page</p>
<div class="code" data-type="css">
// i am a weird page with very tiny fonts
html {
font-size: 10px;
}
// thats ok i am sizing everything relative to your tiny fonts
.ui.menu {
font-size: 1rem;
}
// i am sizing relative to the menu element
.ui.menu .menu {
margin-left: 0.5em;
font-size: 0.9em;
font-size: 0.8em;
}
</div>
</div>
<h2>Coding Guidelines</h2>
<div class="example">
<h4 class="ui header">Prevent Accidental Highlighting</h4>
<p>Sometimes text can be accidentally highlighted when a user double clicks an element. No need to pull out javascript to solve this.</p>
<div class="code" data-type="css">
.ui.thingy {
-webkit-user-select: none;
-moz-user-select: none;
-ms-user-select: none;
user-select: none;
}
</div>
</div>
<div class="example">
<h4 class="ui header">Joining borders</h4>
<p>Sometimes bordered content must sit next to other bordered content. If each element uses border the borders will double. Consider using either outline or a box shadow to accomplish the same effect but without overlapping borders.</p>
<div class="code" data-type="css">
// this might not go so well
.ui.thingy {
border: 1px solid #DDDDDD;
}
// rgba is great, but keep in mind the overlapping borders will be added together to create a darker shade
.ui.thingy {
outline: 1px solid rgba(0, 0, 0, 0.1);
}
// classic but works
.ui.thingy {
outline: 1px solid #DDDDDD;
}
// this works too
.ui.thingy {
-moz-box-shadow: 0px 0px 0px 1px #DDDDDD;
-webkit-box-shadow: 0px 0px 0px 1px #DDDDDD;
box-shadow: 0px 0px 0px 1px #DDDDDD;
}
</div>
</div>
<div class="example">
<h4 class="ui header">Using transparency</h4>
<p>RGBA colors in css allow you to specify colors with a transparency channel. This is very useful.</p>
@ -123,7 +215,7 @@ type : 'UI Specification'
background-color: #FAFAFA;
color: rgba(0, 0, 0, 0.7);
}
.ui.red.thingy {
.red.ui.thingy {
background-color: #FF0000;
}
</div>
@ -160,7 +252,7 @@ type : 'UI Specification'
<div class="example">
<h4 class="ui header">Onion Skinning</h4>
<p>One technique that is useful for allowing for infinite color variations of an element, without having to completely reskin each variation and shade, is to use background color and background-image together to define colors.</p>
<p>One technique that is useful for allowing for multiple color variations of an element, without having to completely reskin each variation and shade is to use background-image gradients to define shading and state, and background-color to define the color of an element. If done well you can add a variety of colors with very little code.</p>
<div class="code" data-type="css">
.ui.thingy {
background-color: #FAFAFA;
@ -168,6 +260,12 @@ type : 'UI Specification'
.ui.red.thingy {
background-color: #FF0000;
}
.ui.green.thingy {
background-color: #00FF00;
}
.ui.blue.thingy {
background-color: #0000FF;
}
.ui.thingy:hover {
background-image:
-webkit-gradient(linear, 0 0, 0 100%, from(rgba(0, 0, 0, 0.1)), to(rgba(0, 0, 0, 0.05)))

27
node/src/documents/specification/htmlguide.html
View File

@ -0,0 +1,27 @@
---
layout : 'default'
css : 'guide'
title : 'HTML Guide'
type : 'UI Specification'
---
<div class="segment">
<div class="container">
<h1 class="ui header">HTML Guide</h1>
</div>
</div>
<div class="main container">
<h2>Writing HTML</h2>
<p>All components should be namespaced to avoid collisions with other components. For example, if you decide that your element is a "button", then all rules should begin with .ui.button or .ui.button. For more details see our html and css guidelines.</p>
<p>Components may contain html elements inside which do not have to be subclassed as ui. For example here is the code for a progress bar</p>
<div class="code">
<div class="ui progress">
<div class="bar"></div>
</div>
</div>
</div>

5
node/src/documents/specification/styleguide.html
View File

@ -18,6 +18,11 @@ type : 'UI Specification'
<p>The following are some guidelines which help avoid some common pitfalls in writing UI element definitions.</p>
<div class="example">
<h4 class="ui header">Neutral Base Form</h4>
<p>In order to make UI components be able to exist in most websites, the prototype version of an element should be neutrally styled using greytones and neutral colors. This will allow other elements to be more robust giving other developers freedom to make decisions about color and style when adapting your element for their website.</p>
<h4 class="ui header">Commonality</h4>
<p>Try to use the most obvious names for classes. If you're not sure, prototype the element, then ask a friend or two what they would call it.<p>
<div class="code" data-type="css">

Write Preview
Loading…
Cancel
Save