1 files changed, 99 insertions, 0 deletions
diff --git a/doc/tiles.rst b/doc/tiles.rst
new file mode 100644
index 0000000..0855a2f
--- /dev/null
+++ b/doc/tiles.rst
@@ -0,0 +1,99 @@
+=====
+Tiles
+=====
+
+Every tile consists of an obligatory ``.html`` file and two optional ``.css``
+and ``.js`` files. All three files belonging to a tile should have the same
+name that corresponds with the tile name – e.g. with the ``pie_chart`` tile
+these are ``pie_chart.html``, ``pie_chart.css`` and ``pie_chart.js`` files
+respectively.
+
+Customising tiles
+-----------------
+
+If you want to modify a tile (e.g. change a CSS attribute, which obviously
+cannot be done via API), copy a desired file in the folder of tiles delivered
+with the application (i.e.
+``<path_to_your_virtualenv>/lib/python2.7/site-packages/tipboard/tiles``),
+paste it in your tile folder (i.e. ``~/.tipboard/custom_tiles``) and edit
+according to your needs.
+
+Files in your ``custom_tiles`` folder take precedence over those shipped by
+default with the application and thus you can easily replace desired elements
+(e.g. if you want to change the text colour, just copy and edit the ``.css``
+file – without touching ``.html`` and ``.js`` files). We plan to introduce a
+command simplifying this process in the future.
+
+Color palette
+-------------
+
+Color palette used by Tipboard's tiles is defined as shown in the table below.
+To retain consistency, we strongly suggest sticking to them while customising
+tiles.
+
++-------------+---------------------+
+| Value       | Name                |
++=============+=====================+
+| ``#000000`` | ``black``           |
++-------------+---------------------+
+| ``#FFFFFF`` | ``white``           |
++-------------+---------------------+
+| ``#25282D`` | ``tile_background`` |
++-------------+---------------------+
+| ``#DC5945`` | ``red``             |
++-------------+---------------------+
+| ``#FF9618`` | ``yellow``          |
++-------------+---------------------+
+| ``#94C140`` | ``green``           |
++-------------+---------------------+
+| ``#12B0C5`` | ``blue``            |
++-------------+---------------------+
+| ``#9C4274`` | ``violet``          |
++-------------+---------------------+
+| ``#EC663C`` | ``orange``          |
++-------------+---------------------+
+| ``#54C5C0`` | ``naval``           |
++-------------+---------------------+
+
+Common elements
+---------------
+
+* tile's content (``data`` key) and its configuration (``value`` key) should be
+  send as two separate requests - once you have established desired
+  configuration it does not make much sense to send it over and over again;
+* in order to reset tile's config, you just send an empty ``value`` key (e.g.
+  ``value = {}``).
+
+.. _tiles_library:
+
+Library of available tiles
+--------------------------
+
+In the following pages we present a "library" of available tiles (i.e. those
+bundled with the application), which should serve as a specification how to
+send data to them and how to set up its configuration options.
+
+.. toctree::
+   :maxdepth: 2
+
+   tile__text
+   tile__pie_chart
+   tile__line_chart
+   tile__cumulative_flow
+   tile__simple_percentage
+   tile__listing
+   tile__bar_chart
+   tile__fancy_listing
+   tile__big_value
+   tile__just_value
+   tile__advanced_plot
+   tile__norm_chart
+
+.. note::
+
+   In order to keep brevity, all examples presented in specifications above do
+   not include any escape characters. Therefore, it's up to you to insert them
+   where necessary.
+
+   And also, remember to set all the elements in angle brackets (e.g.
+   ``<api_key>``, ``<tile_id>`` etc.) to reflect your configuration.