You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

195 lines
6.7 KiB

11 years ago
11 years ago
11 years ago
11 years ago
11 years ago
11 years ago
11 years ago
11 years ago
11 years ago
11 years ago
11 years ago
11 years ago
11 years ago
11 years ago
11 years ago
11 years ago
11 years ago
11 years ago
11 years ago
11 years ago
11 years ago
11 years ago
11 years ago
11 years ago
11 years ago
11 years ago
11 years ago
11 years ago
11 years ago
11 years ago
11 years ago
11 years ago
11 years ago
11 years ago
11 years ago
11 years ago
11 years ago
11 years ago
11 years ago
11 years ago
11 years ago
11 years ago
11 years ago
11 years ago
11 years ago
11 years ago
11 years ago
11 years ago
11 years ago
11 years ago
11 years ago
11 years ago
11 years ago
11 years ago
11 years ago
11 years ago
11 years ago
11 years ago
11 years ago
11 years ago
11 years ago
11 years ago
11 years ago
11 years ago
11 years ago
11 years ago
11 years ago
11 years ago
11 years ago
11 years ago
11 years ago
11 years ago
11 years ago
11 years ago
  1. # Semantic
  2. Semantic is a set of specifications for sharing UI elements between developers. Semantic is also a UI library to make front end development simpler and easier to learn.
  3. ## Development Status
  4. Semantic is pre-release. Build tools are not yet available, and APIs may be updated regularly prior to 1.0, so be warned!
  5. Please [share any issues](https://github.com/jlukic/Semantic-UI/issues?state=open) you may have, we need your help to get all the kinks out.
  6. If you need to create a test case, you can [fork this jsfiddle](http://jsfiddle.net/jlukic/Vbr9d/1/) to get you started.
  7. If you want to keep track of development, please [join our google group](https://groups.google.com/forum/?hl=en#!forum/semantic-ui)
  8. ## The Library
  9. ### Getting Started
  10. The Semantic library describes many UI elements. In most instances it might be best to build a custom build with only the elements you need.
  11. *Build tools are not yet available but stay tuned!*
  12. ~~You can use our build tool to select only the components you want~~
  13. To download the entire library
  14. git clone git@github.com:quirkyinc/semantic.git
  15. If you prefer to download the whole kit as a zip, it is so conveniently packaged.
  16. http://semantic-ui.com/build/semantic.zip
  17. ## The Specification
  18. The aim of the specification is to develop conventions around structuring and naming code for interface elements.
  19. By defining a vocabulary the development community can exchange javascript and css definitions of UI in a similar language, making new code easier to grok, and reducing the complexity of starting a new project, or changing a sites design.
  20. ## Types of UI
  21. UI components are split into four categories, ranging from smallest to largest in scope:
  22. * UI Elements
  23. * UI Collections
  24. * UI Modules
  25. * UI Views
  26. ### UI Elements
  27. UI Elements are interface elements which do not contain other elements inside themselves. This can be thought of as similar in definition as an "element" in chemistry.
  28. UI elements can have plural definitions when they are known to exist together frequently.
  29. In this case each button will be large because we understand it is a part of the large button group
  30. ``` html
  31. <div class="large ui buttons">
  32. <div class="ui button">Cancel</div>
  33. <div class="ui button">Continue</div>
  34. </div>
  35. ```
  36. Examples of UI elements:
  37. * Buttons
  38. * Labels
  39. * Headers
  40. * Progress bars
  41. ### UI Collections
  42. UI Collections are groups of heteregeneous UI elements which are usually found together. Carrying the chemistry metaphor, these can be thought of as molecules.
  43. UI collections have a definition of elements that exist, or could exist inside of them. They do not usually require all elements to be found, but they describe a list of the "usual suspects". Unlike elements, collections are not typically useful to define in plural.
  44. Examples of UI collections:
  45. * Forms
  46. * Tables
  47. * Grids (Layout)
  48. * Menus
  49. ### UI Modules
  50. UI modules are elements where it's behavior is a fundamental part of its definition. UI Modules are dependent on the javascript which carry their definition. They also may be more complex, and have a variety of different functions. Further abusing the scientific analogy: These can be thought of as "organs".
  51. Examples of UI modules:
  52. * Popups
  53. * Modals
  54. * Chatrooms
  55. ### UI Views
  56. UI Views are common ways to structure types of content so that it can be understood more easily. A view's definition in semantic only describes the content which typically occupies the view.
  57. Examples of UI views:
  58. * Comment Feed
  59. * Activity Feed
  60. * Product List
  61. ### How it is defined
  62. #### Scope of a definition
  63. **All UI**: The specification defines class name and html structures which can be used to represent an element
  64. **Elements**: An element definition gives states which an elements can occupy, common types of that element, and if necessary, defines how the element functions in groups.
  65. **Collections**: Collection definitions list elements that it can include, and variations which can apply to both the collection, or individual elements found in the collection.
  66. **Modules**: Module definitions include a list of behaviors that are commonly associated with an element
  67. **Views**: View specifications defines the types of content the view usually display, and the heirarchy typical to presenting this content to the user.
  68. #### Based on class
  69. Semantic is based on class names, instead of tags. This means, except for links, tables and form elements, you can use semantic with tags like ``<div> <article> <nav>`` without any difference.
  70. #### Context sensitive
  71. In Semantic, variations maintain context based on the element they modify, but keep the same vocabulary between elements. Just like how in English, the adjective 'big' may describe a different scale for a big planet versus a big insect.
  72. For example, a form you can have a variation called "inverted". This changes the appearance of form elements to work on dark backgrounds.
  73. ```html
  74. <div class="ui inverted form">
  75. <div class="field">
  76. <label>Name</label>
  77. <input type="text">
  78. </div>
  79. </div>
  80. ```
  81. The same variation can also be useful in the context of a menu.
  82. ```html
  83. <div class="ui inverted menu">
  84. <div class="item">Section 1</div>
  85. <div class="ui simple dropdown item">
  86. Dropdown
  87. <div class="menu">
  88. <div class="item">Dropdown item 1</div>
  89. <div class="item">Dropdown item 2</div>
  90. </div>
  91. </div>
  92. </div>
  93. ```
  94. #### Example
  95. Here is part of Semantic's definition of a button
  96. **Standard**: A button is a shape that can be pressed in to complete an action.
  97. ```html
  98. <div class="ui button"></div>
  99. ```
  100. **State**: A button can sometimes be active, designating it is selected by the user.
  101. ```html
  102. <div class="ui active button">
  103. ```
  104. **Variations**: A button may sometimes look different than its prototype.
  105. ```html
  106. <div class="ui large blue icon button">
  107. <i class="ui icon heart"></i>
  108. </div>
  109. ```
  110. **Plurality**: A button can sometimes exist in a group of buttons
  111. ``` html
  112. <div class="ui large blue buttons">
  113. <div class="ui button">
  114. I am blue
  115. </div>
  116. <div class="ui button">
  117. I am blue too
  118. </div>
  119. </div>
  120. ```
  121. ## Usage
  122. ### Developers
  123. Prereqs Node, Grunt(``npm install -g grunt-cli``) and DocPad (``npm install -g docpad``)
  124. Inside ``node/`` use the command ``docpad run`` to start your server
  125. You can then access the docs locally at ``localhost:9778``
  126. To have DocPad watch for changes while working on a component simply run the command
  127. ``grunt``
  128. To build the release packages for Semantic
  129. ``grunt build``
  130. #### I want to contribute to the spec
  131. Semantic is very new standard, and we need a community to become truly useful. We're working currently to determine the best ways to engage the community for contribution. If you'd like to participate feel free to reach out by e-mail [jack@myfav.es](mailto:jack@myfav.es)